Iterative planning loop
Turn a request into verified work
01 · Request
State the outcome and boundaries.
02 · Explore
Inspect code, history, tests, and decisions.
03 · Ask
Surface unknowns and interview the human.
04 · Prototype
Make options visible and cheap to change.
05 · Refine
Write the current plan and finish line.
06 · Prove
Test the riskiest assumption on a small slice.
07 · Record
Log discoveries and deviations while building.
08 · Revise
Update the plan when evidence changes it.
09 · Verify
Use tests, domain evidence, and a fresh reviewer to check the result.
Planning continues during implementation. New evidence can send the work back to exploration, a prototype, or a revised plan.
## Use this nine-step planning workflow
### 1. Start with the request
State the user or operator outcome, why it matters, and the boundaries the work must respect. Include hard constraints such as data handling, compatibility, permissions, migration rules, and systems the agent may change.
Do not start by dictating a file list unless the files are part of the requirement. The repository may contain a better path.
### 2. Ask for technical exploration
Have the agent inspect the relevant code, tests, documentation, recent history, prior attempts, and current runtime behavior. Ask it to report evidence before it recommends an approach.
Claude Code's official guidance describes its loop as gathering context, taking action, and verifying the result. It also recommends exploring before implementation and giving the agent something concrete to verify against. ([Claude Code documentation](https://code.claude.com/docs/en/how-claude-code-works)) The same planning pattern works with other coding agents that can inspect a repository and run its tools.
### 3. Turn unknowns into questions
Ask the agent what could change the architecture, user behavior, security boundary, migration, or validation strategy. Then have it interview you one question at a time, starting with the answer that would change the plan most.
Shihipar's public [blind-spot example](https://thariqs.github.io/html-effectiveness/unknowns/01-blindspot-pass.html) scans code and history before proposing an authentication change. His [interview example](https://thariqs.github.io/html-effectiveness/unknowns/06-interview.html) orders questions by architectural impact. The useful pattern is evidence first, then focused questions.
### 4. Prototype choices that words cannot settle
Use a small prototype, visual explainer, trace, benchmark, or reference implementation when you will only know the right choice after seeing it work. Ask for several meaningfully different options when the task involves interaction or visual judgment.
HTML is useful for interactive mockups and explainers. Markdown remains better for compact plans and durable text. The [HTML vs. Markdown guide](/learn/code-context/ai-agent-html-vs-markdown) helps choose the format.
### 5. Write the refined plan
Fold the exploration, answers, and prototype decisions into a plan. Put the choices a human might change near the top. Keep routine refactoring and plumbing concise.
Use the [AI coding plan template](/templates/ai-coding-plan) for the outcome, scope, evidence, implementation, risks, validation, and documentation. If you need a broader method with durable project state or feature specifications, use the [planning framework index](/frameworks).
### 6. Build the smallest useful proof
Test the assumption most likely to invalidate the plan. A proof might be one migration against realistic data, one API round trip, one browser interaction, or one performance measurement at a representative size.
Do not use the easiest task as the proof. Prove the part that would make you choose a different design.
### 7. Keep implementation notes
Ask the agent to record what the code revealed, where reality differed from the plan, what choice it made, and what still needs human judgment. For an unexpected but reversible detail, give it a conservative default: preserve existing behavior, data, and access; avoid a new dependency or external side effect; and log the choice.
The agent should stop when a surprise would change product behavior, security, data ownership, a public contract, or an irreversible operation. Shihipar's [implementation-notes example](https://thariqs.github.io/html-effectiveness/unknowns/09-implementation-notes.html) separates discoveries, conservative deviations, and decisions that belong to a human.
### 8. Revise the plan when the evidence changes
Planning did not fail because implementation found something new. Update the current plan, explain the deviation, and retire assumptions that no longer hold. For a material change, return to review before continuing.
Use [Plan Diff](/learn/plan-diff-see-what-changed) to compare an agent's revised plan with the earlier version. The [plan-approval guide](/learn/code-context/approve-ai-coding-plan-before-execution) covers the separate decision to approve the current plan before execution.
### 9. Verify with fresh evidence
Keep coordination, execution, and verification distinct. The coordinator preserves the goal and decisions. The builder implements them. A fresh reviewer, test harness, or domain expert checks the result without inheriting all of the builder's assumptions.
Anthropic's official loops guide recommends a second agent for code review because a reviewer with fresh context is less influenced by the main agent's reasoning. It also recommends clear stop criteria and a pilot before a large run. ([Anthropic loops guide](https://claude.com/blog/getting-started-with-loops)) Independent review still needs repository evidence and human judgment for consequential changes.
## Copy this planning and interview prompt
```text theme={null}
Help me plan this change before writing production code.
Outcome: [what should be true for the user or operator]
Boundaries: [systems, data, compatibility, permissions, and non-goals]
1. Inspect the relevant code, tests, docs, history, and prior attempts.
2. Report the evidence that changes how this work should be designed.
3. Find blind spots in my request. Do not claim completeness.
4. Interview me one question at a time. Ask first about answers that
would change the architecture, product behavior, or validation.
5. Suggest the smallest prototype, explainer, or test that would settle
the riskiest unknown.
6. Write a plan with the decisions I may want to change at the top,
followed by scope, implementation, risks, and validation.
7. Define a finish line. Use measurable checks where they prove the goal,
and a rubric plus human review where quality requires judgment.
8. During implementation, keep notes on discoveries and deviations.
Preserve existing behavior, data, and access when a reversible surprise
is not covered. Stop for consequential or irreversible decisions.
9. After implementation, revise the plan and return the exact checks,
artifacts, unresolved issues, and an independent verification result.
```
This prompt is a starting contract. Delete parts that do not apply. A small, reversible fix may need only the outcome, one code inspection, and a focused test.
## Choose the right finish line
Use a measurable exit condition when the measurement directly proves the requested result. Use a rubric or human judgment when the result includes taste, meaning, risk, or tradeoffs that one number cannot capture.
| Finish line | Works well for | Example | Main risk |
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
| Deterministic check | Binary behavior or contract | All migration fixtures preserve row counts and access rules | The check can omit an important case |
| Numeric threshold | Performance or bounded quality measure | p95 latency stays below 200 ms at the stated load | The agent may optimize the score instead of the experience |
| Reference match | Port, rendering, or compatibility work | Output matches a trusted implementation on a fixed corpus | The reference may not cover local requirements |
| Rubric | Design, writing, or multi-part behavior | Score accessibility, clarity, task completion, and visual fit separately | A vague rubric creates confident but inconsistent grades |
| Human decision | Product judgment or irreversible risk | An owner accepts the tradeoff after seeing the prototype and evidence | The decision can become a bottleneck if requested too often |
Anthropic recommends goal-based loops for tasks with verifiable exit criteria. In the interview, Shihipar contrasts a measurable target with visual work that needs a rubric and a separate verifier. ([Anthropic loops guide](https://claude.com/blog/getting-started-with-loops), [interview](https://www.youtube.com/watch?v=aVO6E181cNU\&t=201s))
## A blind-spot prompt is not a completeness check
An agent can search only the evidence it can reach and reason from the models it already has. If neither the human nor the agent knows what complete looks like, asking for unknown unknowns may produce a polished list that misses the real failure.
Ground the pass with:
* current code, tests, logs, migrations, and prior incidents;
* domain standards, regulations, and security or accessibility checklists;
* reference behavior and representative data;
* explicit rubrics and failure cases;
* an interview with the person who owns the problem; and
* independent verification after implementation.
Treat the blind-spot report as a research queue. Confirm each important claim against a source, a test, or a person with domain knowledge.
## Case study: plan a video workflow by removing unknowns
In Peter Yang's interview with Shihipar, the initial goal was to turn a spoken recording into a rendered video with word-level captions and overlays. The useful planning work happened before the reusable workflow was encoded.
Shihipar first asked the agent to explain how Whisper transcription could fail. The explainer surfaced silence hallucinations, split words, and missing speaker recognition. He then used HTML to explore several overlay styles, which made visual preferences concrete before a more expensive React and video-rendering implementation. His next step was the smallest version that could prove the concept. ([Interview planning segment](https://www.youtube.com/watch?v=aVO6E181cNU\&t=507s))
He described planning as a back-and-forth process: request, technical exploration, mockups or explainers, implementation notes, and a revised specification when the code reveals a new constraint. Peter Yang's public thread distilled the first lesson into a blind-spot pass before building. ([Peter Yang's thread](https://x.com/petergyang/status/2079209983984677210), [public episode notes](https://creatoreconomy.so/p/how-i-plan-build-and-run-loops-with-claude-code-thariq-shihipar))
The example does not prove that every plan should be HTML or that one prompt can find every unknown. It shows why cheap explanations and prototypes belong inside planning when they settle decisions before full implementation.
## Review the current plan and the returned work
Once the unknowns are small enough to proceed, review the current plan instead of an earlier draft. Open-source Plannotator can [annotate an AI coding plan](/open-source/workflows/plan-review), return feedback to the agent, and compare the next submission. The [long-horizon task guide](/learn/ai-development/what-are-long-horizon-tasks-for-ai-agents) explains how to preserve the objective, progress memory, checkpoints, and evidence when execution spans dependent stages or sessions.
Planning does not replace code review. Compare the result with the current plan, inspect the actual diff, run the finish-line checks, and make sure the implementation notes have been folded into maintained documentation.
## Frequently asked questions
### Should a coding-agent plan list every file and edit?
Only when those details expose a boundary or prevent a known mistake. Let repository exploration determine routine file edits. Keep human attention on outcomes, risky choices, constraints, and proof.
### Is this the same as Claude Code plan mode?
No. Plan mode is one product interface for proposing work before execution. This field guide describes a tool-independent discovery loop that may use plan mode, normal conversation, prototypes, tests, and implementation notes.
### When is a one-shot plan enough?
A one-shot plan can be enough for a small, familiar, reversible change with strong tests and no consequential unknown. Use the iterative loop when the task crosses systems, contains product or design judgment, changes data or access, or depends on behavior the team has not verified.
### When should the agent stop and ask a person?
It should stop when new evidence changes the intended behavior, security or privacy boundary, data ownership, public API, migration safety, cost commitment, or another hard-to-reverse decision.