Plan

Produce a plain, implementation-ready plan that shows what code will change and how it will work. Keep small changes short. Prefer concrete pseudocode and real symbols over architecture language.

Investigate

1. Use the existing conversation and already-gathered repository context as the primary source of truth.
2. Inspect the relevant implementation and tests before writing the plan. Trace callers, consumers, registrations, schemas, generated artefacts, and adjacent implementations only as far as the requested change needs.
3. Resolve facts available in the repository before asking the user. Do not submit a plan while paths, symbols, or behaviour remain generic placeholders.
4. Load staged-implementation only when repository inspection finds separate, independently reviewable changes. Otherwise write one dependency-ordered implementation sequence. Do not introduce stages, handoffs, checkpoints, or phase artefacts for a small change.
5. Load writing-style as the prose reference for the visible plan. Apply its plain, concise, concrete, human voice, UK English, and no-em-dash rules. Do not apply its commit-message, pull-request, issue, or action-authorisation instructions to plan structure.
6. Ask only the minimum necessary follow-up questions through the question tool when a requirement or trade-off cannot be inferred and would materially alter the implementation. Resolve those decisions before submitting the plan. Leave an open question in the submitted plan only when execution can safely proceed without resolving it. Do not run a grilling session while planning.
7. Do not propose parallel workers during planning unless the user asks for them. When the user does, follow session-coordination; planning workers remain read-only, and any agreed implementation split is recorded in the plan and launched only once execution is authorised.

Prepare Privately

Before writing the visible plan:

1. Reconcile the plan against every explicit user decision and any grill, research, issue, handoff, or specification decisions already in context. Treat later user feedback as authoritative. Preserve the difference between work deferred from the current turn and work excluded from the implementation.
2. Check scope completeness against every subsystem, workflow, tool, and outcome named by the user. Classify each as included, intentionally unchanged, or deferred with a reason. Do not silently narrow the request to the first implementation area found.
3. Distinguish observed repository facts, settled decisions, assumptions, and unresolved unknowns. Do not present an assumption as a fact or re-open a settled decision without contradictory evidence.
4. Resolve unknowns that affect the core implementation path before submission. Ask before choosing between materially different behaviours, data shapes, adopters, or migration paths. If repository inspection cannot resolve a technical unknown, make a bounded feasibility check the first plan step and state its success criterion, failure criterion, and fallback path. Do not defer core design choices with phrases such as "decide during implementation", "likely", or "possibly".
5. Verify proposed changes to shared interfaces, schemas, paths, persisted data, generated contracts, and public APIs against their producers and known consumers. Include compatibility work only when a concrete shipped, persisted, or external consumer requires it.
6. Keep rejected alternatives, recommendations, decision recaps, research summaries, architecture overviews, and assumptions lists out of the submitted plan. Put settled reasoning beside the implementation step it explains. If a blocking choice remains, ask the user before submitting the plan.

Write The Plan

Use this order:

1. What will happen: Explain the resulting behaviour in one to three plain sentences. Name the first code entry point when useful. Do not include history, alternatives, architecture framing, validation, or repeated scope.
2. Implementation: Give numbered, dependency-ordered code changes. For each step:
   • Name the repository-relative file and existing function, class, type, route, schema, or other insertion point.
   • Explain the actual edit in ordinary language, including the important calls, branches, data shapes, state changes, or rendering conditions. Put the reason for a non-obvious choice immediately beside the edit it explains.
   • Show compact pseudocode immediately beneath that explanation for new or materially changed control flow, state transitions, data transformation, API handling, persistence, or rendering. Use symbols confirmed during repository inspection. When contrasting existing and proposed code, use a fenced diff block with - and + lines so Plannotator renders removals red and additions green. Use the relevant language fence for wholly new pseudocode. If those symbols are not known, inspect further before submitting. Omit pseudocode for skills, prose-only documentation, generated files, simple configuration changes, and trivial renames.
   • Mention required consumers, registrations, imports, translations, migrations, and generated outputs beside the code that creates the need.
   • Apply testing before planning test edits. Name the meaningful failure or important behaviour each added test protects; an existing test file does not itself justify more coverage. Keep test edits beside the behaviour they verify, with their concrete benefit.
3. Validation: Give only the smallest targeted commands or end-to-end observations needed to prove the implementation works. Do not repeat test-file edits already described in the implementation.
4. Files: Include every anticipated changed, added, deleted, generated, or migration file as a directory tree, split by repository or workspace root. Mark generated files with their source of truth. Every file in the tree must appear in an implementation step.

Pseudocode earns its place when it exposes changed code flow more clearly than prose. It must trace inspected project symbols rather than inventing a generic example or placeholder API.

Keep It Direct

• Prefer a small direct implementation over speculative abstractions, compatibility layers, helpers, migrations, or phases.
• Follow the loaded writing-style skill for the plan's prose. Write in the maintainer's direct, practical voice. Avoid generic AI prose: no formal padding, flattering agreement, marketing language, repeated summaries, or long transitions that delay the implementation. Use short sentences and say exactly what the code will do and why.
• Do not use jargon when ordinary language or a code symbol is clearer. Explain an unavoidable technical term once in plain English.
• Do not use verbs such as "update", "wire", "handle", "support", "integrate", or "refactor" instead of saying what the code will do.
• Discuss architecture only where it causes a specific code change. Follow architecture statements immediately with the files, symbols, and pseudocode that implement them.
• Do not add top-level Architecture, Decisions, Assumptions, Research, or Risks sections unless the user explicitly requested that separate analysis. Put any implementation-relevant content from them in the numbered step where it changes the edit.
• Spend most of the plan on implementation. Do not let validation, testing, risks, or coordination artefacts outweigh the code changes.
• Keep detail proportional: one compact step for a small change, several steps for a standard change, and stages only for independently reviewable work.
• For staged work, follow staged-implementation for checkpoints and handoffs, but keep those coordination details after the active implementation rather than ahead of it.

Review And Revise

Before submission, verify that:

• Every acceptance criterion maps to an implementation step and a targeted or final check.
• Every entry in Files appears in a step, and every generated file names its source of truth.
• No requested area disappeared from scope and no settled decision is contradicted.
• No core mechanic remains an unbounded assumption or execution-time decision.
• Every numbered step describes an edit rather than analysis, and every non-obvious reason follows the edit it justifies.
• Pseudocode uses symbols confirmed during repository inspection, and no unresolved choice has been made for the user.
• Before-and-after code examples use fenced diff blocks; wholly new pseudocode uses its language fence.
• Safeguards, compatibility layers, abstractions, and migrations address an observed contract or regression risk rather than speculative hardening. Test edits satisfy testing; a generic regression risk is not enough.
• The visible plan begins with the plain explainer, contains pseudocode where logic changes, and gives implementation more space than validation.

When the user changes a decision after a plan is drafted, perform a contradiction and impact scan. Revise only the affected scope, steps, files, acceptance criteria, risks, and validation unless the change invalidates the plan's foundation.

Finish Planning

Keep the output planning-focused and make no implementation edits while planning. Approval goes through a Plannotator review, which has Approve and Send feedback, never an Inbox question:

• When the client's plan mode hands the plan to a review on exit, end by leaving plan mode.
• Otherwise save the plan to a file and open it with the plannotator tool's annotate action and gate: true (or plannotator annotate <file> --gate --json without the tool).
• When the plannotator_inbox tool is available, also send an Inbox status update in the same turn with the plan in short and a link to the open review. End it with a :::question-text block whose prompt sends the user to the review (for example "Approve or send feedback in the plan review" with the review URL linked) and a Stopped: line, so the thread shows it is waiting. Treat a text answer there as plan feedback; the review stays the place to approve.
• When the review's decision arrives (approved, approved with notes, or feedback), reply in that thread before any edit: put the review question in supersedes, say in a line that the plan was approved (or what the feedback changes) and that implementation starts now, and move the Board card to building when there is one. The Stopped: question must not stand through the implementation.