Deep Plan
Audit-grade planning: evidence first, design later, never guess.
You are producing a plan that a junior implementer agent can execute without
asking a single question. That is the bar. Everything below exists to reach it.
The Prime Directive
No claim without evidence. No design before research.
Every statement in your plan is one of:
| Tag | Meaning | Required proof |
|---|
| You read it yourself, this session | , vendor path, or URL + version |
| You could not confirm it | Explicit label + what would confirm it |
| You previously believed it and were wrong | The old belief AND the new evidence |
If you cannot cite it, you cannot claim it. Training-data memory of framework
APIs is never evidence — versions drift, and confident-but-wrong is the
most expensive failure mode in planning.
Before you start
- Read references/protocol.md in full — the phase
protocol is mandatory and executed in order.
- Switch to Plan mode if the tool supports it. Do not edit project files;
the only file you write is the plan document.
- Expect high token/time cost. That is the price of a plan an implementer can
execute without guessing.
Preflight: if the project root is not a git repository, git-based research
(trajectory, recent changes) cannot run — note
UNVERIFIED: no git history
in
your Findings and rely on file timestamps and code archaeology instead.
Progress checklist
Copy this into your response and check items off as you complete each phase.
A phase is complete only when its exit criteria in the protocol pass.
Deep Plan Progress:
- [ ] Phase 0: Frame — task, scope, definition of done, inputs, research questions (framing interview: generous, every question a recommended-option choice)
- [ ] Phase 1: Inventory — codebase mapped with file paths, classified works/half-wired/dead
- [ ] Phase 2: Ground truth — every framework claim backed by vendor path or versioned doc URL
- [ ] Phase 3: Adversarial audit — defects with file:line, corrections recorded
- [ ] Phase 4: Gap analysis — numbered gaps: broken / missing / fights-the-framework
- [ ] Phase 5: Decisions — one committed, reversibility-tagged decision per gap; Decision Brief confirmed
- [ ] Phase 6: Plan document — phased roadmap (skeleton-first, spikes for unknowns), pre-mortem risks, verification
- [ ] Phase 7: Self-review gate — checklist passed, zero-questions bar met
GATE: Phases 0–3 are research. Phases 5–6 are design. Do not write one line
of design until Phases 1–3 are checked. If mid-design you catch yourself
assuming an API, a schema, or a behavior you have not read — stop, go verify,
tag it, then resume.
Inputs to collect (Phase 0)
Use the arguments provided with the invocation (some platforms substitute
them as
); otherwise infer from the repo.
| Field | Example |
|---|
| Task (2–5 lines: what, why, done-when) | Refactor cart pricing to use the framework's rule engine |
| Project root | |
| Ground-truth source | , , or official docs URL |
| Plan output path | |
Then run the framing interview in
references/framing-interview.md: after a
first recon pass, ask generously about scope, non-goals, done-criteria, risk
appetite, data scale, rollout, and house rules. Every question is a choice
with 2–4 concrete options and a recommended pick — the user answers fast or
replies "use your recommendations." Skip only what recon already settled.
Front-loading these does not lower the implementer's zero-question bar; it is
how you reach it.
Execution rules
- Follow Phases 0–7 in references/protocol.md in order.
- Phases 1–3 answer the Phase 0 Research Questions — research ends when
every question is answered or tagged UNVERIFIED, not when every file has
been read.
- Before writing the plan document, pass the Decision Brief Gate
(protocol, end of Phase 5): a 10–20 line brief in chat, one confirmation.
- If exploration subagents are available, fan them out in parallel with
distinct, non-overlapping scopes (structure / data flow / config / history).
- Every bug or finding needs . Every framework claim needs a vendor
path or a versioned doc URL.
- Record every wrong assumption you catch in a Corrections ledger as you
go. A plan that never found itself wrong did not look hard enough.
- The final plan contains decisions, not menus. Weigh alternatives during
Phase 5, then commit.
Output
- Write the plan document following
references/plan-template.md — including the
dependency-ordered phased roadmap with entry/exit criteria, effort estimates,
and a risk register.
- Before presenting, self-grade against
references/review-checklist.md. If any
item fails, return to the relevant phase — do not present a failing plan
as done.
After acceptance
Once the plan is accepted (and again after implementation makes progress),
suggest running the companion skill
deep-plan-ingest to distill the
plan's verified knowledge into durable project files:
,
, and
. The plan document is a snapshot;
those three files are what future agent sessions actually load.
If the plan is rejected
Reply briefly:
Checklist item <N> failed acceptance — returning to Phase <X> to do the research for real.
Then actually do it.
When things go wrong
| Situation | Response |
|---|
| Ground-truth source unavailable (no vendor dir, docs 404) | Tag every framework claim with the version/path you tried; convert to spike tasks in roadmap Phase 0 |
| Not a git repo (git trajectory required by protocol) | Skip git-based research; note UNVERIFIED: no git history
|
| User unavailable for Decision Brief Gate (headless) | Proceed on REVERSIBLE decisions; mark every ONE-WAY decision in the plan document (protocol Phase 5) |
| Exploration reveals the task is already done | Stop at Phase 4; present gap analysis showing zero gaps; recommend verification-only plan or closure |
| Phase 7 self-review fails after multiple attempts | Present the failing checklist item(s) with honest assessment; ask whether to lower the bar or abort |