Multi Pass Planning

Multi-Pass Planning

When to use this skill

• Task touches more than one file or module
• Task changes architecture, public API, or shared state
• Task requires new or updated tests or documentation
• Assumptions are unclear, unverified, or based on memory
• A previous attempt produced a sprawling diff or required rework
• The user has asked for a plan, design, or approach before changes

If a boundary-definition spec already exists for this work, use it as the input to the Plan pass.

Core principle

The first plan is always wrong in places that are not yet visible. Treat planning as four short passes plus one execution pass. Each pass has a single job and a single output. Do not collapse passes. Skipping Audit or Repair is the most common cause of agentic rework.

Procedure

1. Plan pass. Produce a numbered list of steps. Each step names the files touched and the observable outcome. Do not code.
2. Audit pass. Re-read the plan adversarially. For each step, write the assumption it relies on, what could break it, and the evidence supporting it. List every unverified assumption explicitly.
3. Repair pass. For each unverified assumption, do one of: read the code, run a probe command, or ask the user. Update the plan. Mark each assumption Verified, Removed, or Still unknown.
4. Align pass. Confirm the updated plan still satisfies the original intent and any active boundary specs. Every step must map to an item in the spec or the original request, or it is deleted.
5. Code pass. Execute the plan step by step. If reality contradicts the plan during execution, stop and re-enter the Audit pass. Do not patch the plan in-place while coding.

Do not code yet until passes 1–4 are complete and Still unknown is empty.

Required output format

Five labeled sections in the working document or reply:

## Plan
1.  —  — 
2. ...

## Audit
- Step 1
  - Assumption: ...
  - Risk: ...
  - Evidence: ...
- Step 2
  - ...

## Repair
- Verified: ...
- Removed: ...
- Still unknown: ...   # must be empty before Code pass

## Align

## Code

Stop conditions / escalation triggers

• Repair pass leaves any item in Still unknown — escalate to the user, do not start coding
• Align pass shows the plan no longer matches the original intent — restart from Plan pass
• During Code pass, any single step requires changes in more than one place in the plan — return to Audit pass
• The plan grows past roughly 12 steps — split the task and re-plan each part
• An assumption requires running destructive or shared-state commands to verify — confirm with user first

Short examples

Good Audit entry:

> Step 4: rename loadUser to fetchUser. Assumption: only called from src/api and src/cli. Risk: dynamic imports or string-based lookups. Evidence: needs a repo-wide grep of loadUser and 'loadUser'.

Bad Audit entry (rejected):

> Step 4: should be fine.

No assumption, no risk, no evidence. This is what the Audit pass exists to prevent.

Good Repair note:

> Verified: ran grep -r "loadUser" src — only two callers, both updated in step 5. Removed: nothing. Still unknown: none.

Good Align paragraph:

> The plan delivers the new fetchUser shape required by the Boundary Spec, updates both callers, and adds a behavioral test for the new error case. No steps are out of scope; nothing in the spec is unaddressed.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zoidbergclawd
• Source: zoidbergclawd/coherence
• License: MIT

Install and usage instructions live in the source repository linked above.