Iterative Planning Prompts You Can Copy

Getting Started Beginner ~20 min Published:

What you'll learn

Introduction

Give an a one-line request and it will come back with something finished: a confident plan, a tidy document, a working branch. That finished thing is easy to see and easy to check. It is the : the measurable output.

What you actually wanted is the : the choices you would have made, the constraints you know about and didn't mention, the option you would have ruled out on sight. An agent can't read those from a one-liner, so it fills the gaps with reasonable defaults and writes them in the same voice as the facts. Every question you never answered gets answered anyway.

The four prompts here change the shape of the session so that doesn't happen. Each one makes the agent write down what it knows early, show you the gaps, and ask you about them in small pieces before it moves on. They are short on purpose. You can paste them into Claude Code, opencode, Codex CLI, ChatGPT or any other assistant that can keep a markdown file up to date, and they work the same way.

Text in angle brackets, like <describe the feature>, is the only part you fill in. Everything else is meant to be pasted as is.

Prompt 1: Iterative Plan Building

When to use it. You're about to change something in a codebase and there are decisions in it: where a thing lives, what happens on failure, what to keep compatible. Use this before any code is written, in a session where the agent can read the repository. 

We are going to build a plan for <describe the feature or change>
together. The plan is a markdown file at <plans/name.md>. Create it
now if it doesn't exist. Follow these rules for the whole session:

- Write what you know when you know it. As soon as you understand a
  constraint, a fact about the code, or a decision I've made, put it
  in the plan. It should always show your current best understanding,
  even when it's incomplete.
- Surface open questions as you find them. Add each one to an
  "Open Questions" section the moment it comes up.
- Read before you claim. If the plan touches code you can access,
  open the relevant files before saying how anything works. Don't
  guess what a file contains.
- Make no edits during planning. The plan is the only file you
  change. No code, no fixes, not even a one-line one.
- Ask me one question at a time. For each: why it matters, the
  realistic options and what each costs, and your leaning. Then stop
  and wait for my answer.
- Form your leaning when we reach the question, not in advance.
  Weigh maintainability, security and the long term over what is
  quickest to build, and say what your choice gives up.
- Never mark a question decided until I have answered it. When I do,
  record my answer and my reason in the plan, add any new questions
  it raised, then move to the next one.
- Keep iterating until every open question is decided and I say the
  plan is final.

What it changes. Without it, most agents read a little, decide a lot, and present the result. With it, the agent reads first, writes facts into the file as it finds them, and turns every judgment call into a question with options. The plan file grows during the conversation instead of appearing at the end, so if the session dies you still have everything learned so far.

Two rules do most of the work. One question at a time stops the agent from batching five decisions into a list you skim and approve with "sounds good". Leaning formed live stops it from deciding everything up front and then walking you through its conclusions. A leaning written before you've discussed the earlier questions can't include what you said in them.

How to adapt it. If there's no codebase (a process change, a migration of documents), drop the "read before you claim" line or point it at whatever source of truth you do have. If your agent tends to act when you ask a question, prefix your answers with "just discuss" until the plan is final. If you care about something specific, add it to the leaning line: "weigh cost to run" or "weigh what our support team will have to explain".

What good output looks like. A single question turn, then a stop:

Q2: Should the CSV export run in the request, or as a background job?

Why it matters: the largest account has about 400k rows. I read
export/views.py: the current JSON export builds the whole response in
memory and the request timeout is 30 seconds.

(a) In the request, streamed row by row. No new moving parts; a slow
    client holds a worker for the whole download.
(b) Background job that emails a link. Survives any size; needs a
    place to store files and a cleanup rule for them.
(c) In the request, capped at 50k rows. Simplest; the largest
    accounts can't export everything.

Leaning: (b). Account sizes only grow, and (a) ties worker capacity
to client speed. What it gives up: (a) needs no storage and no
cleanup, which (b) adds.

Waiting for your answer before Q3.

Facts it checked, real options with costs, a leaning that names its own downside, and nothing decided. If you want a stricter version of this, with a separate agent walking the questions and markers that keep the rejected options in the file, that's what Plans That Record Decisions, Not Guesses sets up. This prompt is the lighter, single-session version.

Prompt 2: Research and Brainstorming Document

When to use it. You don't have a plan yet. You have an idea, a question, an article you want to build on, or a tradeoff you keep going back and forth on. You want a document at the end, and you'd rather think out loud than write a brief. 

Help me think through <the idea, question, or tradeoff>. We'll build
a markdown document together over a few rounds.

- Create the document right away, before asking me anything. Draft a
  structure from what I've given you, fill in what you know or can
  reason out, and mark gaps with [TBD].
- Then ask me 2 to 4 specific questions, each with a line on why
  you're asking. Not ten. Don't ask what you can reasonably infer or
  look up yourself.
- I'll answer what I know and skip the rest. Half-formed answers are
  fine; work with them.
- After each round, update the document. Resolve [TBD]s and develop
  the thinking: add reasoning, connections, and any tension or
  tradeoff you notice. Don't just transcribe my answers.
- Keep what is established separate from what is a working guess,
  and keep open questions in their own section.
- After each update, tell me in a line or two what changed, then ask
  the next 2 to 4 questions.
- Don't polish wording while the ideas are still moving. Stop when I
  say the document captures it.

What it changes. The usual failure here goes one of two ways. Either the assistant interviews you with a dozen questions before producing anything, or it writes a polished essay from your one sentence. The first wears you out; the second is the extension problem again, a complete-looking document full of positions you never took.

Drafting first gives you something to react to, and reacting is easier than specifying. Small batches matter because answers change what's worth asking next. A batch of twelve gets skimmed and half-answered, and the six questions your first answer made irrelevant still sit in the list.

How to adapt it. Tell it which shape of document you want. The four we use most, each with the sections to ask for:

If you're pasting source material, add “cite which source each finding came from”. Expect one to four rounds. If you're on round six, the question is probably too broad; split it.

What good output looks like. The first draft, before any questions:

# Self-Hosted Search: Exploration

## The Core Question
- Is it worth running our own search service instead of the hosted one?

## What We Know
- Hosted search costs grow with query volume (from your note)
- [TBD] current monthly volume and the bill

## Working Thesis
- Probably not yet: running it means owning upgrades and on-call,
  which a team of three may not want. Subject to the numbers.

## Tensions
- Cost at scale vs. operating burden now
- Control over ranking vs. time spent tuning it

## Open Questions
1. Who would be on call for it?
2. Is ranking quality a complaint today, or only a future worry?

Then two or three questions, not ten. After you answer, the next version should contain something you didn't say: a consequence, a connection, a tension between two of your answers.

Prompt 3: Interview the Codebase First

When to use it. You're about to change a project you don't know well, or you suspect hidden constraints, and you don't yet know what you want. Before deciding anything, get the coding agent, which can read every file, to tell you how the project actually works. We call this intelligence gathering. It comes before a plan or a , not instead of one.

Send these four questions to the coding agent first, before anything else: 

Only investigate and answer these questions. Do not implement
anything yet. Do not take shortcuts; we need full and thorough answers.

1. What is this project, and what problem does it solve, in one
   sentence?
2. What are the main components or services, and how do they talk to
   each other?
3. What does the API surface look like: the most important endpoints
   or entry points an outside caller would use?
4. What persistent storage exists: what gets saved, where, and in what
   format?

What it changes. Together the four answers tell you what the thing is, how it's built inside, how the outside world reaches it, and what state it keeps. That's enough to start a document. Start it the moment you send the questions, with [TBD] wherever you don't know yet, and fill it in as answers arrive rather than saving everything for the end.

Keep it honest by asking about the code as it is, without saying what you plan to build. If you ask “we're adding a word-cloud plugin; how does the plugin system work?”, the answer describes the plugin system in terms of word clouds and softens the inconvenient parts. “How does the plugin system work?” gets you what's there.

How to run the rounds. After the base questions, send follow-ups two to four at a time. A finding in one round often makes a planned question irrelevant or reveals a better one, and an agent given twelve questions at once skims. Route each question to whoever can answer it: intent, priorities and outside constraints to the person; anything about how the code works to the coding agent. Do another round when an answer surprised you, a [TBD] still blocks the document, or a finding opened an area you didn't know to ask about. Stop when you have enough to decide, not when you know everything.

What you get. A record of what you learned, and often a short list of what would have to change. It isn't an implementation brief yet. That's the next prompt.

Prompt 4: Write the Handoff

A handoff is the written brief you give the agent that will do the work: what you found, what you want, and what must not break, complete enough that it can proceed without the conversation that produced it. It describes the outcome and leaves the method to the agent, which can see the code.

When to use it. You know what you want changed and need to brief the agent that will build it. This prompt goes to the assistant helping you write the brief, which can be the same tool as the coding agent in a separate session, or a chat assistant in another window. 

Help me write a handoff document for a coding agent that will
implement <describe the change>. It's a markdown file named
<project-doctype.md>, for example search-bug-investigation.md.

- Create it now. Put a one-line description at the top and this note
  under it: "This document describes findings, goals, and
  constraints. You have liberty in how you implement. Use your
  judgment and knowledge of the codebase to find the best approach."
- Write findings, goals, and constraints, not steps. "The edit form
  needs more room than the list" is a goal. "Change the layout to a
  30/70 grid" is a prescription; leave it out.
- State findings plainly: "this breaks because X", not "maybe look
  at X". Say what must not break. Number items in priority order.
- Put every unresolved question in one Open Questions section at the
  bottom, never inside a finding.
- Ask me 2 to 4 questions at a time, only about intent, priorities,
  and constraints from outside the code. Technical questions about
  the codebase go to the coding agent, not to me.
- When a technical question needs answering, draft it for me to send
  to the coding agent. Ask how the code works now, neutrally. Do not
  describe the feature we are planning in those questions. Start each
  batch with: "Only investigate and answer these questions. Do not
  implement anything yet. Do not take shortcuts; we need full and
  thorough answers."
- Update the document as answers come in and tell me what changed.
- Before we call it done, ask whether I have anything to add, confirm
  Open Questions is empty, and check that no implementation steps
  crept in. End the document with: "Do not edit this document.
  Implement it, then report what you changed and anything you
  couldn't do."

What it changes. The brief carries your intent and leaves the method to the agent that can see the code. A prescribed implementation gets followed literally, including where it's wrong, and the agent stops looking for the better approach you'd have accepted. Goals and constraints tell it what “done” means and what it may not break, which is the part only you know.

How to adapt it. Name the kind of handoff in the file name and the first line. The same rules cover all of them:

What good output looks like.

# Publishing Settings: Findings & Goals

Review findings from hands-on testing of the publishing settings page.

> This document describes findings, goals, and constraints. You have
> liberty in how you implement. Use your judgment and knowledge of
> the codebase to find the best approach.

## 1. The "Master Password" label is misleading
- The field is an encryption password, not a login password.
- **Goal:** the label says what the password is for.
- **Constraint:** existing stored credentials must keep working.

## 2. The edit form is cramped
- The even split gives the list space the form needs.
- **Goal:** the form gets more room; the list stays usable.
- **Constraint:** must work with 1 destination and with 20+.

## Open Questions
(none)

Do not edit this document. Implement it, then report what you
changed and anything you couldn't do.

Notice what's missing: no file names to edit, no component structure, no CSS. If those creep in, the brief is doing the coding agent's job with less information than it has.

Using Them Together

The four prompts chain. A research document settles whether and what. Interviewing the codebase tells you what's really there. A plan settles the decisions inside the change. A handoff packages the decided plan for the agent that builds it. You won't need all four every time: a small fix might go straight to a handoff, and some research documents end with “not now”. For how this fits into a full pipeline, from filing an item to landing it, see How We Build With Agents Now.

What the four share is one habit: write what you know when you know it, in a file, and keep the gaps visible until a person fills them. A document with honest [TBD] marks is more useful than a complete one that guessed.

Try it yourself

Pick one change you've been meaning to make that has at least one real decision in it.

  1. Run Prompt 1 in a session that can read the repository. Count how many files the agent opens before its first question. If it's zero, remind it of the "read before you claim" rule.
  2. Answer at least one question with something outside the options it offered. Check that the plan records your answer in your words, not the nearest option.
  3. When the plan is final, start a new session with Prompt 4 and turn the plan into a handoff. Read the result and strike any line that tells the agent how rather than what.
  4. Hand it to a coding agent. Compare what it built with what you'd have prescribed. Note anywhere it found a better approach, and anywhere a constraint you forgot to write down was broken.

The forgotten constraints are the useful finding. Each one is a line for the next handoff.

Key Takeaways

  • A confident plan or a finished document is the extension. Your intent is the intension, and an agent working alone fills its gaps with guesses.
  • Iterative plan building: write facts as they're found, surface questions as they appear, read code before claiming anything, no edits, one question at a time with options and a long-term leaning.
  • Research documents: draft first, then 2 to 4 questions per round, and make each revision add thinking, not just your answers.
  • Before changing an unfamiliar project, interview the coding agent: four base questions, then follow-ups two to four at a time, until you know enough to decide.
  • A handoff is the brief for the agent that does the work: findings, goals and constraints, never steps. Give it liberty in how it implements.
  • Ask a coding agent about the code as it is, without describing what you plan to build, or its answers lean toward your plan.
  • Keep the gaps visible. A [TBD] a person fills beats an answer an agent assumed.

Next Steps

← Back to all tutorials