Improve Plan

Use this workflow to strengthen an existing feature plan in a single fluid pass.

Critical Constraints

• NO IMPLEMENTATION: You are strictly FORBIDDEN from modifying any project source files. Your ONLY permissible write action is updating the existing Feature Plan document.
• CONTENT PRESERVATION (two-tier):
  • Factual context — NEVER delete. Goal statements, product scope, requirements, constraints, environment details, and problem/background analysis must be preserved verbatim. This includes product scope explicitly stated in the plan's Goal or Problem Description — you must not narrow or remove supported scenarios (e.g. multi-root workspaces) even if the current session is single-repo. If you believe a goal or scope statement is wrong, flag it in chat for the user — do not unilaterally correct it.

  • Reasoning outputs — correct with audit marking. Conclusions, chosen approaches, design decisions, and code examples may be corrected or replaced when the improve pass produces a better alternative. Every correction MUST be marked with a superseded callout so the change is auditable:

    Superseded: <original conclusion or approach> Reason: <why it was wrong or inferior> Replaced with: <new conclusion or approach>

    Never silently delete a conclusion and write a new one in its place. The callout is the audit trail — without it, the change is a protocol violation.

• SESSION vs PRODUCT SCOPE: Session directives (e.g. "single-repo", "skip compilation", "skip tests") constrain HOW you verify and organize the plan, not WHAT the plan covers. Do not conflate repo structure constraints with product feature requirements. If the plan targets multi-root workspaces, you must preserve and improve that scope regardless of the current session's repo configuration. Never transcribe a session directive into the plan file — not as a note, a caveat, or an explanation of what this run did or did not do. It binds you, not the reader. Written down it inverts: a later coder reads a constraint on the planner as an instruction to itself, and follows the document over the live dispatch that contradicts it.
• SINGLE PASS: Complete enhancement, dependency checks, the architecture challenge (Step 4), adversarial critique, balanced synthesis, the Goal-consistency pass (Step 6), and plan update in one continuous response.

Target is a feature? Use improve-feature instead

If the target file is under .switchboard/features/ or contains an auto-generated <!-- BEGIN SUBTASKS ... --> block, this is a feature, not a single plan. Stop and use the improve-feature workflow — it improves every subtask and is authorised to restructure the set (merge/delete/rewrite/split). This improve-plan workflow is for a single plan and is deliberately non-destructive, which is the wrong contract for a feature.

Steps

1. Load the plan
   • Read the target plan file and treat it as the single source of truth.
   • Read the actual code for any services, utilities, or modules referenced by the plan.
2. Assess scope — flag if split needed. Before strengthening, check whether the plan covers 3+ distinct deliverables or 2+ independently-shippable phases. If so, surface that in chat and recommend splitting (write separate plan files for each deliverable/phase) or promoting to a feature via create-feature-from-plans — do not silently strengthen a mega-plan. This skill is single-plan and non-destructive, so it cannot retroactively split mid-improve; the recommendation is the action, the user decides. If the plan is genuinely single-scope, proceed to step 3.

3. Improve the plan

   • Fill in underspecified sections and break work into clear execution steps with file paths and line numbers.
   • Ensure the plan has ALL of the following sections (add any that are missing):

   Required Sections (in order):

   1. ## Goal - 1-2 sentences summarizing the objective, followed by any core problem, background, or root-cause analysis (always preserve and do not drop existing analysis)
   2. ## Metadata
      • Tags: [frontend, backend, auth, authentication, database, api, ui, ux, bugfix, feature, refactor, test, docs, security, performance, reliability, mobile, devops, infrastructure, cli, library]
      • Do NOT invent tags outside the allowed list. If no tags apply, write Tags: none
      • Complexity: 1-10
      • Repo: Bare sub-repo folder name if applicable
   3. ## User Review Required

   Project Pinning

   When creating or updating a plan, include **Project:** <name> in the Metadata section if a project is active or the user named one. The workspace/repo name is NOT a project — never pin it (the importer silently drops workspace-name pins to unassigned). If no project is active and the user didn't name one, omit the line — never ask the user which project to use. See AGENTS.md "Plan Project Pinning" for the full protocol.

   4. ## Complexity Audit

      • ### Routine — bullet points or plain text listing routine aspects
      • ### Complex / Risky — bullet points or plain text listing complex/risky aspects (or "- None" if empty)

      Recommended format (parser is flexible):

      ## Complexity Audit
      
      ### Routine
      - [routine aspect 1]
      - [routine aspect 2]
      
      ### Complex / Risky
      - [complex aspect 1]
      - [or "- None" if no complex aspects]

   5. ## Edge-Case & Dependency Audit
      • Race Conditions, Security, Side Effects, Dependencies & Conflicts
   6. ## Dependencies
      • sess_XXXXXXXXXXXXX — <topic> format
   7. ## Adversarial Synthesis
      • 2-3 sentence Risk Summary
   8. ## Proposed Changes

      • [Target File]

        • Context, Logic, Implementation, Edge Cases
   9. ## Verification Plan

      • Automated Tests

      • ### Goal Invariants (RECOMMENDED — not required, never a gate)
        • Executable assertions that name concrete paths, symbols, or counts — not prose. A vacuous invariant like "assert the feature works" is a schema violation, not compliance.
        • Each invariant is a single checkable statement: "X exists at path Y", "X is absent from path Y", "count of X equals N", "symbol X in file Y has property Z".
        • If the goal is a removal or relocation (the Goal contains any of: move, relocate, remove, delete, retire, stop, out of, no longer), a negative invariant is mandatory — assert the thing is gone from where the goal says it should not be. A negative assertion must be paired with a positive one: absent here, resolvable there. "Assert .agents/protocols/ is absent" passes if someone deletes the directory without migrating the content; the paired positive "assert the protocols are resolvable at their new location" catches that.
        • This section gives the reviewer something concrete to measure against the plan's purpose, not just its steps. It is useful precisely when there is no PRD — the plan's own Goal is the only intent baseline, and the invariants make that intent testable.
        • Never a gate. A plan without ### Goal Invariants is valid and passes review. This section is recommended, not required — it must not become a board-wide check that rejects third-party plans authored under a different methodology.
   10. ## Outstanding Questions (OPTIONAL — include ONLY when something is genuinely unresolved; omit the heading entirely otherwise)

       ## Outstanding Questions
       - **[user]** <question needing a human decision> — proceeding on the assumption that <assumption>
       - **[research]** <thing needing external sources, stated as a specific question> — proceeding on the assumption that <assumption>

       • Omit the heading entirely when there is nothing outstanding. Its presence is the signal. An empty-but-present section is a schema violation, not "done" — it forces every reader to parse prose to decide whether the plan is blocked.
       • Every item states the question and the assumption you proceeded under, so the plan stays coherent and codeable before anyone answers.
       • You continue and complete the work regardless. Never block waiting for an answer.
       • This section is additive and must never displace a required section — in particular the problem / root-cause analysis that belongs in or below ## Goal stays where it is.
       • A [user] item costs a human turn. Earn it. Before you write one, clear all four:
         1. Is it verifiable? If the answer is in the code, the schema, the git history, or the board, go and read it. A question you could have answered by grepping is not a decision.
         2. Is it already decided? Search the contents of .switchboard/plans/, not the titles — the same idea is often filed under different vocabulary (a design filed under "streams" will not match a search for "steps"). If a sibling plan settles it, cite that plan and proceed. If a sibling plan contradicts it, the sibling's premise wins and the conflict belongs in that plan, not as a fresh question here.
         3. Is the premise true? Confirm the thing you are asking about actually exists and behaves as you assume. Most rejected questions were asking about behaviour that was never there.
         4. Is it in scope? A question about work this plan does not do is scope drift. Drop it.
       • Never re-ask what this plan was built from. When a plan was written from an operator's stated decision, questions generated while drafting it are yours to resolve from that statement — putting them back to the operator is a loop with no exit.
       • A [user] item is a genuine fork: two defensible options, different outcomes, and no fact in the repo picks between them. Everything else you decide, record as a stated assumption in the plan body, and move on.

   Complexity Criteria:

   • Routine (1-4): Single-file, localized changes. Reuses existing patterns. Low risk. Small scope.
   • Complex/Risky (7-10): Multi-file coordination. New architectural patterns. Data consistency risks. Breaking changes.
   • Mixed (5-6): Majority routine but with one or two moderate, well-scoped risks extending existing patterns.
   • Do not add net-new product scope unless strictly implied by the existing plan.
   • You may add clarifying implementation detail only if strictly implied by existing requirements; label it as "Clarification", not a new requirement.

   Scoring Guide:

   • 1-2: Very Low — trivial config/copy changes
   • 3-4: Low — routine single-file changes
   • 5-6: Medium — multi-file changes, moderate logic
   • 7-8: High — new patterns, complex state, security-sensitive
   • 9-10: Very High — architectural changes, new framework integrations

4. Challenge the approach (architecture review) — ALWAYS run; NEVER gate on complexity

   Self-assessed complexity is unreliable: the most dangerous plans are the ones an agent under-scores ("this looks small"). So this step runs on every plan regardless of the Complexity score, and BEFORE the execution-level critique in the next step.

   Begin by answering in one line: does this plan embody a real approach/design choice, or is it a purely mechanical change (typo, copy, config, single-call bugfix) with no design surface?

   • If genuinely mechanical → write "No design choice — mechanical change" and proceed to Step 5. You must state this explicitly; you may NOT skip it silently. A wrong "this is mechanical" is exactly the failure this step exists to catch, so claim it only when there is truly nothing to decide.
   • Otherwise, challenge the approach the plan commits to:
     • Name it. State the plan's chosen approach in one sentence — the structure/pattern/mechanism, not the goal.
     • Alternatives. List 2–3 genuinely different approaches that could meet the same goal; one line of trade-off each. Two candidates are mandatory in every set: (i) the smallest change that satisfies the ## Goal as written, and (ii) keep the current spec unchanged. Both must be stated and, if rejected, rejected with a reason. Without them the set contains only mechanisms, “best of the set” can only ratchet upward, and supersede has no downward gear — which is how a plan acquires machinery its Goal never asked for.
     • Justify or supersede. Argue why the plan's approach is the best of the set — OR, if an alternative is clearly better, correct the plan's approach with a Superseded callout and flag it in chat. Do not stay inside the plan's frame just because it is the frame. A supersede may not widen the Goal. If the replacement is more general than what it replaces — it serves more callers, more cases, or more shapes — the callout's Reason line MUST quote the ## Goal clause that requires the generality. If no Goal text requires it, you may not supersede: flag the observation in chat and leave the narrower approach in place. “The old spec only covered case A, and case B exists” is an observation, not a licence — case B may already be served by something simpler, or may not need serving at all. Preserving the Goal verbatim (see CONTENT PRESERVATION) protects it from being narrowed; this rule protects it from being overruled by a later section, which is the same defect from the other side.
     • Goal-vs-appearance probe (the load-bearing question): does this approach actually achieve the stated goal, or only appear to? Name any way the plan could pass its own success check while the real goal is unmet — e.g. a completeness metric that counts scaffolding as "done"; an interface that abstracts a call without decoupling the logic behind it; a surface that is reachable but not usable (e.g. returns success but no data). If such a gap exists, it is a top finding — a green metric is NEVER a substitute for this judgment.
     • Surplus probe (the converse, and equally load-bearing): does this approach deliver more than the ## Goal requires? Name every capability it adds that no Goal clause asks for, and for each, name what it now depends on that the Goal does not. Surplus is not free: it imports the reliability of whatever it is built on. A generalisation that needs a field to be populated, ordered or stable inherits every case where that field is empty, unordered or cleared — failure modes the Goal never created and no one signed up for. If you cannot point at the Goal text that demands the generality, it is scope, not rigour. Treat it as a top finding, exactly as an under-delivery gap.
   • Output: write this architecture review to the chat response (like the Grumpy critique below), so the user can see the approach was actually challenged and veto it. It is separate from, and precedes, the execution-level adversarial review.
5. Run the internal adversarial review
   • First, produce a sharp Grumpy-style critique focused on assumptions, risks, race conditions, missing error handling, and validation gaps. Adopt a dramatic "Grumpy Architect" voice — incisive, specific, and theatrical. This voice is part of the planner's quality standard and must be preserved regardless of output-compression directives.
   • Immediately follow with a balanced synthesis that keeps valid concerns, rejects weak ones, and converges on the strongest execution strategy.
   • Output: Write the full Grumpy and Balanced critiques to the chat response as formatted markdown — do not only write them to the plan file. The user must be able to read the critique directly in chat without opening the plan. In the plan file's ## Adversarial Synthesis section, include only a 2-3 sentence Risk Summary (e.g., "Key risks: X, Y, Z. Mitigations: A, B."). Output the adversarial critique exactly once. Do not repeat it.

6. Consistency pass — read the plan against its own Goal before you write it back

   The last thing you do before writing: re-read ## Goal, then read ## Proposed Changes as if you were the coder who will build only from it. Every mechanism in Proposed Changes must trace to a Goal clause, or be explicitly marked out of Goal scope. Where the two disagree, the Goal wins — correct Proposed Changes, not the Goal (the Goal is factual context and is preserved verbatim; see CONTENT PRESERVATION).

   State the outcome in one line in chat: "Goal and Proposed Changes are consistent", or name each divergence and what you did about it.

   This step exists because the pipeline has no other check for it. Every downstream gate — review, contract suites, the goal verdict — asks whether the CODE matches the PLAN. None asks whether the plan matches itself, so a plan that specifies two incompatible things passes every gate and the contradiction is only discovered after a coder has built the wrong half. This is the cheapest place in the chain to catch it, and the only place that catches it before the work is done.

   Measured case, 2026-09-21 — plan 9bb74844 (A Seat Says submit and a Lead Says accept 3). Its ## Goal read "Two verbs, no identity arguments, no UUIDs — accept 3: a lead: subtask 3 is accepted." A later improve pass superseded the resolution mechanism with a generalised ordered-candidate rule covering non-feature callers, recorded in a fully protocol-compliant callout. The coder implemented the superseded section faithfully; six CRITICAL findings followed, every one a property of machinery the Goal never asked for. The Goal was preserved verbatim throughout and no rule was broken. A non-feature caller holds one card, so the pre-existing bare accept already served it — the surplus needed ownerSeat/ownerSince to be populated and stably ordered, which on a live board they are not.

7. Update the original plan file
   • Write the improvement findings back into the same feature plan file.
   • Preserve all factual context (goal statements, requirements, constraints, scope) per the CONTENT PRESERVATION rule. Correct superseded conclusions and approaches using superseded callout blocks — never silently delete.
   • Mark completed checklist items when appropriate.
   • End with a recommendation based on complexity:
     • If complexity is 1-3 → "Send to Intern"
     • If complexity is 4-6 → "Send to Coder"
     • If complexity is 7-10 → "Send to Lead Coder"

Unattended runs

When the dispatching prompt says this run is unattended (it carries an UNATTENDED IMPROVER CONTRACT: block), these override the defaults above. They apply only on that signal — an attended, single-plan improve is unchanged, and asking the user is still correct there.

• Never ask questions in chat — no one is attached to this session. If you need a user decision or external research, append it to the plan's ## Outstanding Questions section, state the assumption you are proceeding under, and finish the work.
• You are improving exactly one plan: the one named in your prompt. Do not create, modify, rename or delete any other file in .switchboard/plans/. Other workers are concurrently improving sibling plans in this same directory; touching their files will destroy their work.
• Step 2 still applies as a recommendation, not as a write. If the plan should be split, record that under ## Outstanding Questions as a [user] item. Do not write the split files, and do not invoke create-feature-from-plans.
• Write the plan file once, at the end. The pass treats the first plan-file mtime advance after dispatch as your completion signal; later writes arrive after the card is already done.

Post-Review Board State

1. Trigger Model: This improve-plan workflow is triggered automatically when a card arrives in the "PLAN REVIEWED" column (which has autobanEnabled: true and role: 'planner'). The card is already in the "PLAN REVIEWED" column when this workflow runs. Do NOT instruct the user to move it there.
2. Review Complete: After completing the adversarial review and plan update, the card stays in the "PLAN REVIEWED" column. The activity light clears on the next plan-file edit. The user advances the card to the next pipeline stage (e.g. dispatches a coder) manually when ready.
3. Plan Metadata: Do NOT write a **Plan ID:** line — it is never parsed. The importer assigns the ID (a fresh UUID, or a feature's filename UUID) and keys plan identity by the file path; a hand-written Plan ID is ignored and drifts from the real DB-assigned one.
4. Feature Relationships: Feature relationships are carried by **Feature:** <feature-plan-id> and **Project:** <name> lines written directly in each plan .md — the plan watcher applies these on import with apply-if-empty semantics. If you restructured plans into a feature during review, recommend invoking the create-feature-from-plans skill (which runs create-feature.js to handle DB update, subtask linking, feature file write, and board refresh atomically) AFTER the review is finished and the user has approved. Do NOT invoke it mid-review.

The Superseded Callout — Format Specification

Placement: Inline, at the location of the original conclusion being corrected.

Format:

> **Superseded:** <original conclusion, approach, or code snippet>
> **Reason:** <concise explanation of why it was wrong or inferior>
> **Replaced with:** <new conclusion or approach>

Rules:

1. The **Superseded:** line must contain the original text (or a faithful summary if it was long). Do not paraphrase in a way that hides what was actually said.
2. The **Reason:** line is mandatory. A correction without a stated reason is a silent deletion with extra steps.
3. The **Replaced with:** line must immediately follow. If the replacement is long (e.g. a code block), it may continue below the callout.
4. Multiple corrections in the same plan are fine — each gets its own callout.
5. The callout replaces the original text in the document body. Do not leave the original text outside the callout AND inside it — that duplicates the contradiction.

Example:

> **Superseded:** Use a polling loop with 500ms interval to detect file changes.
> **Reason:** Polling wastes CPU and introduces up to 500ms latency. The codebase already has a file watcher utility (`src/utils/watcher.ts`) that uses native FS events.
> **Replaced with:** Use `watchFileChanges()` from `src/utils/watcher.ts` — subscribes to native FS events, zero polling overhead, sub-10ms latency.