Explain intent, then test the design

Give enough context to act

Separate unclear intent from missing context

Lauren identifies two common failures. The agent may misunderstand the request, or it may lack the information needed to carry it out. More detailed implementation instructions do not necessarily solve either problem. These failures need different responses. Clarify the desired outcome when the agent has misunderstood it. Supply the relevant files, history, or observations when it understands the goal but cannot investigate or implement it with the context available.

Leave room for a better solution

Describe the desired outcome and constraints. If you prescribe every implementation step, the agent has less room to find an approach you did not consider. The article presents this as a supervision style, not proof that agents always know best.

Ask for the problem in plain language

Use an indirect prompt

Ask the agent to read the report and restate the underlying issue before proposing a fix. This gives you a small, concrete statement to correct before code changes begin. The restatement lets you check whether the agent understood the report before committing to its diagnosis. Correct the description of the observed problem first. A proposed cause can then be tested against that shared understanding.

Avoid planting your diagnosis too early

A guessed cause can steer the investigation toward the wrong answer. Start with observations and let the agent explain what it thinks they mean. You can then compare its interpretation with yours.

Research behavior and history separately

Ask how when you need the execution path

Trace what calls what, where data moves, and which modules own the behavior. The article describes /how as a way to build this current-state picture. This answers a present-tense question about the system. The result should explain the path from a user action to the visible outcome, including where state lives. It need not guess why an earlier engineer chose that structure.

Ask why when you need the decision history

Source code shows what exists. Git history, issues, discussions, and incident reports may explain the reasons. /why gathers that context; /teach combines mechanism and rationale.

Recover prior work deliberately

The /recall workflow finds earlier conversations and project history. A new session should recover relevant decisions rather than rely on the model having remembered them.

Plan through the future user experience

Write a tutorial before implementing the API

Describe how someone would actually use the proposed package. Concrete imports, calls, and expected results reveal awkward design choices that abstract planning can hide. A tutorial exposes the caller's work. If a simple task requires confusing setup or knowledge of hidden state, the proposed interface needs attention before its implementation grows. Expected outputs also give later verification a concrete target.

Use the right kind of documentation

The article uses Diataxis to distinguish a learning tutorial, a task-specific how-to, a technical reference, and an explanation of tradeoffs. These answer different reader questions.

Compare working alternatives

Do not settle a design debate with prose alone

Build a few small implementations when the best interaction or architecture is uncertain. Run them, capture the behavior, and compare the result. The alternatives need to differ in a way that can settle the uncertainty. For a UI, compare the actual interaction. For an API, try the intended caller's task. A longer written argument cannot substitute for observing those results.

Let experiments answer open questions

A temporary UI switcher can expose two or three variants. Timings and recordings give the reviewer something concrete to judge. The point is to reduce uncertainty before committing to the full build.

Sketch the structure before the bodies

Ground the design in existing constraints

The /architect workflow first studies current behavior and its history. It then compares independent sketches of types, signatures, and call sites before implementation. The sketch should make the new code's responsibilities and dependencies visible before the function bodies fill in. Studying the existing system prevents a neat-looking design from overlooking behavior that the migration still needs to support.

Use implementation trouble as design feedback

If the sketch leads to forced casts or awkward state handling, revisit it. The article explicitly allows discarding the design rather than defending it because work has already begun.

Make investigations and migrations reviewable

Ask for evidence and hypotheses separately

For an ambiguous bug, request what is known, which data supports it, and which explanations remain untested. This keeps a plausible guess from becoming an assumed fact. A useful investigation separates the observed failure from possible causes. State what the evidence establishes and what experiment could distinguish the remaining explanations. That lets the next step test a specific question instead of defending an early guess.

Break a migration into verifiable changes

The migration example asks for small pull requests with live verification and visual checks. A compatibility migration may deliberately preserve existing behavior, including bugs, while changing the underlying implementation.