implementation-plan

Implementation Plan

A plan's job is to surface the things the user might actually need to alter, before changing them becomes expensive. Order it by likelihood of change, not by execution order.

Workflow

1. Check the escape hatch. If the change is single-file, touches no interface, data, or UX, and has only one sensible way to do it, say so in one sentence and start — no plan. If a reviewed plan for this task already exists, do not rewrite it: confirm it still stands, then start implementing with implementation-notes.
2. Gather the inputs. Collect what this plan is based on: the brainstorm, spec, interview decisions (from earlier in the conversation, or from interview-decisions.md in the project root if the interview ran in a previous session), an existing implementation-plan.md when continuing earlier planning, the porting checklist from an earlier reference hunt (porting-checklist.md, if present), any chosen prototype under ./design-directions/, plus a read of the code that will be touched. If the chat contradicts interview-decisions.md, the latest chat statement wins — but promote the conflict to a pinned decision entry ("changed from X per your latest comment — confirm?"). If key inputs are missing: when the missing answers would overturn more than one top decision, run interview-me first; otherwise record explicit assumptions marked "(assumed — not confirmed)" and pin them at the top of the decision section regardless of sort order.
3. Sort by likelihood of change, not chronology. Lead with the decisions the user is most likely to tweak — data model and schema changes, new type interfaces and API shapes, anything user-facing (examples; the authoritative sort key is in Rules). Bury the mechanical refactoring at the bottom — the user trusts the agent on that part.
4. Make the top decisions reviewable. For each high-change-risk decision: the chosen option, 1-2 alternatives considered, and what changing it later would cost.
5. Mark the improvisation zones. Flag the areas where unknowns are likely to surface mid-implementation, and state the fallback posture for each (e.g. "pick the conservative option and log it").
6. End with an explicit go/no-go. Present the plan in chat — decision list first — and ask the user to approve, adjust, or reject. If review spans sessions or more than one round, persist the current draft as implementation-plan.md marked status: draft (apply the step 6 exclude when first writing it); flip it to approved on approval. On a vague pass ("looks fine, go ahead"), treat only the decisions actually discussed as approved: restate each undiscussed high-risk decision in one line, then persist.
7. On approval, persist and hand off. Write the approved plan to implementation-plan.md in the project root (or flip the draft's status), in the language of the conversation, using the skeleton below. If the file already exists from a different task, never overwrite it silently: append a new plan section, or rename the old file to implementation-plan-<date>.md and say so. Do not commit it unless the user asks. If this is a git repo, exclude it locally: n=implementation-plan.md; p="$(git rev-parse --git-path info/exclude 2>/dev/null)" && { mkdir -p "$(dirname "$p")" && { grep -qxF "$n" "$p" || echo "$n" >> "$p"; }; } 2>/dev/null || echo "note: could not exclude $n — leaving it untracked, never staging it" Then suggest starting implementation in a fresh session with implementation-plan.md (and any prototypes) passed in as artifacts. Either way, once implementation kicks off — especially in a new session — keep notes per the implementation-notes skill, with implementation-plan.md as the Context input of implementation-notes.md.