name	fd-plan
description	Iteratively plan a feature/fix design (FD) document with the user via in-file checkbox Q&A, folding answers into the spec until signed off. Use when the user asks you to "plan FD-XXX", "work on FD-XXX", "iterate on FD-XXX", or to turn a rough plan document into a fully specified one before any code is written.
metadata	argument-hint <FD-id or plan file path>

FD Plan Iteration

This skill runs a tight, in-file question-and-answer loop that refines a plan document (an "FD" — feature design / fix design) until the user has signed it off. No code is written while this skill is running. The goal is to reach a spec where every decision is explicit, every open question is closed, and every user correction has been folded back into the relevant section(s) of the document — not just recorded as an answer.

When to use

Invoke this skill when:

• The user says "plan FD-XXX", "let's work on FD-XXX", "iterate on FD-XXX", "flesh out FD-XXX", "review my answers in FD-XXX", or similar.
• A plan document exists under .plans/ (typically .plans/FD/FD-XXX - ....md but also .plans/PRD/..., .plans/*.md) and the user wants to refine it before implementing.
• The user says "I answered the open questions, review and update" — that's the middle of this loop, resume it.

Do NOT invoke this skill when:

• The user has asked for code changes directly. This skill never writes code.
• The user is asking a quick question about an existing FD. Just read it and answer.

Locating the plan file

1. If the user passed an argument that looks like a file path, read that path.
2. If they passed an ID (e.g. FD-005, PRD-foo, 005), glob for it under .plans/**/ and pick the matching file. Ignore *TEMPLATE* files.
3. If nothing matches or there are multiple candidates, ask the user which file they meant. Do not guess.
4. Always confirm the file path in your first reply so the user can correct you before you start editing.

The iteration loop

Each cycle of the loop has four beats:

Beat 1 — Read current state

Read the full plan file. Identify:

• Which sections of the spec are still vague (hand-wavy, TODO-ish, or contradicting each other)
• The current "Open questions" / "Decisions" / similar section — what's answered, what isn't
• Any checkboxes the user has ticked or notes they've added since the last read
• Any new requirements the user added directly into prose sections

Beat 2 — Process user answers

If the user has answered questions since last time:

• Fold each answer into EVERY section of the spec it affects — not just the questions area. If an answer changes the label rules, rewrite the Label Rules section. If it changes data fetching, rewrite the Data section. If it changes click behaviour, rewrite the Click Handler section.
• A decision is "processed" only when the spec reads consistently as if the decision was always there. Leaving a resolved answer orphaned in the Open Questions area while the main spec still says something contradictory is a failure mode — do not do it.
• Watch for answers that contradict things you wrote earlier in this skill's run. Reconcile explicitly; never silently keep the old wording.
• Watch for answers that reveal a project-wide preference (e.g. "never hide, always disable", "use root scripts not cd", "en-AU spelling"). These belong in memory via the auto-memory system, not just in this one FD.

Beat 3 — Raise new questions

Answers almost always raise new questions. Surface them in the plan file using the in-file format below — NOT just in chat. The user works through these in their IDE and the plan is the durable artefact.

In-file question format:

For a question with discrete options, use checkboxes the user can tick directly in the file:

#### QX. {short question title}
{One or two sentences explaining the question and why it matters.}

- [ ] Option A — {short description of what this option means and when it's right}
- [ ] Option B — {short description}
- [ ] Option C — {short description}
- [ ] Other — notes:
  - _{your note here}_

**Notes / reasoning:**
- _{anything you want me to know about the pick}_

Rules for writing questions:

• Every question gets a "Notes" slot. The user can always fill it with an alternative or a reason.
• Give your current recommendation inline. If you think Option B is right, say so in Option B's description and explain the tradeoff in one line. The user is busy; don't make them derive your opinion from scratch.
• Never ask the user to pick between options you haven't described. Vague questions like "how should we handle X?" are a failure mode — always offer concrete options.
• Don't ask questions whose answers are already derivable from the codebase. Read the code first. Ask the user only for judgement calls (UX choices, priorities, scope), not facts you could grep for.
• Questions have IDs (Q1, Q1a, Q1b, Q2, ...) so subsequent conversation can reference them precisely.
• Cap one round at ~3 questions. More than that and you're not iterating, you're running a survey. If you have more, pick the ones that unblock the most other decisions first.

Beat 4 — Report back and wait

Send the user a terse message (≤120 words) summarising:

• What you changed in the spec based on their answers
• What new questions you raised (by ID) and where to find them in the file
• One unilateral decision you made if you had to make one — flag it so they can override

Then stop. The user will either answer the new questions (another cycle begins) or sign off.

Managing the decision trail

Over multiple cycles the plan accumulates answered questions. Keep them visible but compact so the document doesn't bloat:

• Under ## Open questions, only keep questions that are actually still open (unchecked or partially answered). Everything resolved moves to a "Decisions" or "Decision trail" section.
• Use a table format for resolved decisions — the user has expressed this preference (columns: ✅, Question, Decision, Why). Keep each Why cell to one sentence so the table scans fast.
• Order the table by when each question was raised, not alphabetically. The order itself carries information about how the design evolved.
• When a question is resolved, fold the answer into the main spec FIRST, then move the question to the decisions table. Never skip the fold-in step.

Sign-off gate

You are finished ONLY when:

1. Every question in the file is answered (no unticked checkboxes in open questions, no {your note here} placeholders the user was expected to fill).
2. The spec sections (Problem, Data, Label rules, Click handler, Files to modify, Verification, etc.) are self-consistent — you could hand the document to someone cold and they could implement it.
3. The user has explicitly confirmed they want to proceed. Common sign-off phrases: "looks good, start coding", "go", "implement it", "ship it", "approved". If the user's latest message doesn't clearly sign off, ask: "Is this ready to implement, or do you want another pass?" — one sentence, then stop.

Until all three are true, stay in the loop. Do not write any code. Do not start edits to the implementation files. Do not even read the implementation files unless you need them to answer a planning question.

Hard rules

• No code edits during this skill. Only edits to the plan file and (where justified) to the user's memory system.
• Always fold answers into the main spec. Orphaned answers in an "Open questions" area while the rest of the spec is stale is the most common failure mode of this skill — guard against it.
• Never hide questions from the user by asking them only in chat. If it's a decision that shapes the spec, it goes in the file with a notes slot. Chat is for terse status updates between cycles.
• Respect the no-hiding / disabled preference and other project-wide preferences stored in memory. If a question touches one of them, default to the memory's answer and only raise the question if there's a real tension.
• Watch for project-wide feedback while iterating. If the user tells you something that clearly applies beyond this FD ("I prefer X over Y everywhere"), save it to auto-memory in the same cycle you're folding it into the spec — don't wait for a separate invitation.
• Keep update messages terse. The plan file is the durable artefact. Chat messages between cycles should be ≤120 words and never repeat content that's already in the file.
• Ask before guessing. If an answer is ambiguous, raise it as a new question in the next cycle rather than picking unilaterally. If you must pick unilaterally because the decision is tiny and blocks progress, flag it explicitly in the chat summary so the user can override.

Example cycle

Initial state: .plans/FD/FD-007 - dashboard - filter persistence.md exists with a rough problem statement, no open questions, no data section.

Cycle 1:

• Read the file.
• Spec is sparse; you can tell the filter-state persistence layer isn't specified.
• Add an "Open questions" section with Q1 (where to persist: localStorage / URL params / server), Q2 (which filters to persist), Q3 (how to handle stale filters after schema changes). Each has checkbox options + notes slots + your recommendation inline.
• Send a chat message: "Drafted 3 questions at the bottom of FD-007. Q1 is the main unlock — tick one and I'll build the rest around your choice."
• Stop.

Cycle 2 (user ticks Q1 "URL params" and adds a note on Q2):

• Read the file.
• Fold "URL params" into a new "Data / persistence" section, update "Files to Modify" to mention the router code, update Verification to include URL state checks.
• Process Q2's note as a partial answer; raise Q2a as a follow-up sub-question.
• Move Q1 to a new "Decisions" table.
• Send a chat message: "Folded URL-params decision into sections 3 and 5. Raised Q2a about the filter namespacing — take a look."
• Stop.

Cycle N (user says "looks good, ship it"):

• Verify sign-off gate conditions.
• Confirm in chat: "Signed off. Switching out of planning mode — want me to start the implementation now?"
• Exit the skill. Implementation is a separate task.