plan-feature

name	plan-feature
description	Plan a new feature, phase, or significant change for an existing project. Reads the codebase and existing docs first, then runs a focused conversation to produce a scoped plan document at documentation/<feature>-plan.md. Use when adding capabilities to a project that already has code and architecture in place.
user-invocable	true

Plan Feature

Run a structured planning conversation for a new feature or phase in an existing project, then produce a scoped plan document. Unlike plan-init (greenfield), this skill starts by reading what already exists so questions focus only on the delta.

Invocation

/plan-feature [optional: feature name or one-liner]

If the user provides a feature name or description inline, use it to seed Phase 2 and skip redundant questions.

Pipeline position

Step 1 of the plan pipeline: plan-feature → plan-review → plan-wrap → repo-sync → build-phase. /plan-expedite autonomously chains the three intermediate stages (plan-review-autofix → plan-wrap-autofix → repo-sync → session-wrap) so /build-phase gets a clean, sync'd plan to walk. Always surface the closing-message contract below so the chain can't be skipped accidentally.

After writing the plan file, end your turn by surfacing the recommended next move: the produced plan must pass /plan-review and /plan-wrap BEFORE /repo-sync mints GitHub issues — a gap caught after sync is an N+1-edit problem (1 plan-doc fix + N issue-body edits). The autonomous chain that handles this for you is /plan-expedite --plan documentation/<slug>-plan.md, followed by /build-phase --plan documentation/<slug>-plan.md once /plan-expedite returns READY.

Before the conversation — auto-discovery

Before asking anything, silently read and internalize:

1. Producing files for any value the feature will reference — open the actual source file (schemas, CLI flags, package scripts, endpoint paths, config values) BEFORE drafting the plan, not the docs that describe them. Stale docs are a recurring source of plan-level Blockers: wrong reward schema, missing API response shapes, npm start vs npm run dev have all bitten prior phases. Examples of what to read first: rewards.py, package.json scripts section, pyproject.toml dependencies, the actual route handler (not just the OpenAPI doc).
2. Project docs — README, CLAUDE.md, AGENTS.md, any existing documentation/*.md plans
3. Master plan or multi-phase architecture document — if the project has a master plan or roadmap defining its phase sequence (common shape: a documentation/master-plan.md or top-level architecture doc that splits work into Phase 1, 2, 3, …), locate the section for the phase you're planning and extract: scope boundaries already decided, design decisions already made upstream, and the step-number range reserved for prior phases (so this feature's build steps continue where the master plan expects rather than restarting at Step 1). Step-number collisions across sibling plans corrupt /repo-sync issue bodies — see feedback_repo_sync_step_collision.md for the failure mode.
4. Project structure — top-level directory tree, src/ layout, test layout
5. Existing patterns — imports, frameworks, test tooling, build config (pyproject.toml, package.json, Cargo.toml, etc.)
6. Git state — current branch, recent commits (last 10-15), any open work
7. Memory — check project memory files for active work, past decisions, gotchas

This gives you the project baseline. Do NOT ask the user to re-explain things the code already answers (language, framework, database, test runner, etc.).

Conversation phases

Work through these phases in order. Ask questions as a conversation — group related ones, skip what you already know from auto-discovery, and listen for implied answers.

If the user front-loads many answers, still walk through every phase: summarize what you understood, confirm it, and ask about gaps.

---

Phase 1 — Existing landscape

Summarize what you learned from auto-discovery in 3-5 bullet points:

• Project purpose and current state
• Key modules and their responsibilities
• Relevant existing patterns, conventions, or constraints
• Any active work or recent changes that might interact

Cite the producing file each bullet came from — e.g., "per rewards.py", "per package.json scripts" — not "per the README". The README is allowed to be stale; producing files are not.

Ask: "Does this summary look right, or is anything stale/missing?"

---

Phase 2 — Feature goal

• What does this feature do in one sentence?
• Who benefits (same users, new users, developers, CI)?
• What is explicitly out of scope for this feature?
• Is there a triggering event — user request, bug, tech debt, new requirement?

---

Phase 3 — Impact analysis

Based on the feature goal and your knowledge of the codebase:

• Which existing modules will be modified?
• What new modules or files need to be created?
• Are there any existing patterns this should follow (e.g. "add a new command like the existing ones in src/commands/")?
• Does this feature touch shared code that other features depend on?
• Any migration or backwards-compatibility concerns?
• For each function signature, schema field, or shared constant being changed, grep ALL call sites in the codebase and list each in the impact table. Don't trust "probably only file X uses this" without verifying. Anchor: Alpha4Gate Phase 4.6 Step 1 — an SC2Env._game_id shape change missed the evaluator._get_game_result consumer; 70-minute soak-4 DB forensics found the gap and cost a whole Phase 4.7 re-plan cycle. See feedback_grep_all_downstream_when_fixing_key_shape.md.

Present your analysis and ask the user to confirm or correct.

---

Phase 4 — New design decisions

Only ask about decisions this feature introduces — not ones the project has already made.

• Does this feature need new data entities or schema changes?
• Does it introduce new external dependencies (APIs, libraries, services)?
• Are there new async/background operations?
• Are there new user-facing interfaces (CLI commands, API routes, UI pages)?
• Any new auth/permissions considerations?
• Does this feature add or extend any autonomous, scheduled, background, or "always-on" behavior? If yes:
  • How will you know the new behavior actually works end-to-end, beyond unit tests of each component? Time-dependent failures (cumulative drift, race conditions, scheduled-trigger logic, alert thresholds, integration with other autonomous components from prior phases) are invisible to short test runs.
  • Will the build steps include a deliberate observation phase where the full system runs with realistic inputs and is watched long enough to expose those failures? If not, surface this as a follow-up phase and flag it before saving.
  • This is especially important when the feature is observability infrastructure (dashboards, alerts, monitoring) for an existing autonomous system — it is very tempting to ship the observation tooling without ever actually running it against real autonomous behavior. Avoid that trap.
• Are there multiple valid approaches? If so, present options with tradeoffs and ask the user to pick.

Skip any category that genuinely doesn't apply.

---

Phase 5 — Build steps

• Step numbering inherits from the master plan when one exists. If auto-discovery found a master plan / multi-phase roadmap, start this feature's step numbering in the range the master plan reserved for this phase — do NOT default to Step 1 if prior phases already used Steps 1-N. Step-number collisions across sibling plans break /repo-sync (see feedback_repo_sync_step_collision.md).

• What are the natural steps to build this feature? (Size each as one vertical slice — see ../../references/step-authoring.md §1; don't over-split a coherent slice.)

• What order minimizes risk and maximizes testability at each step?

• Can any steps be built in parallel?

• What does "done" look like for each step? (specific test, behavior, output)

• What /build-step flags does each step need?

  • --reviewers defaults to --reviewers code in plans this skill produces. code runs the 4-agent gauntlet (correctness, bugs, test quality, style) over the diff — sufficient for backend logic, docs, scripts, and config edits. Escalate only when the step has a real runtime/UI surface to validate. Values:
    • code (default) — 4-agent diff review.
    • runtime — 3 evidence-based agents (UI / backend log / frontend). Requires --start-cmd + --url. Use when the step changes visible UI behavior.
    • full — all 7 agents. Requires --start-cmd + --url. Use for full-stack steps spanning backend logic AND visible UI.
    • auto — gates only (no agents). Use for mechanical scaffolding / wiring where the test suite is the entire reviewer.
    • Auth-gate downgrade: if the URL exposed by the step is behind a PIN, login screen, or any auth flow a fresh Playwright session cannot satisfy, downgrade runtime/full back to code — the runtime reviewers cannot reach the URL, so their evidence will be empty and they will produce false-negative blocks. Reference: Alpha4Gate Phase 4.6 reviewer-flag mismatch cost 2 iterations to correct full → code at /build-phase time.
    • Decision tree for picking --reviewers:

Propose a step order with flags and ask the user to adjust.

---

After the conversation

Once phases 1-5 are complete, produce documentation/<feature-slug>-plan.md with these sections. Every numbered section is required — adapt the depth, not the presence.

1. What This Feature Does — one-paragraph description, including why it's being built

2. Existing Context — brief summary of relevant existing architecture, modules, and patterns this feature builds on (so a fresh-context model can orient without reading the whole codebase)

3. Scope — what's in, what's explicitly out

4. Impact Analysis — table of existing files/modules affected. Required columns: File, Change Type (modify/extend/refactor/delete), Reason, and Verified. The Verified column records HOW the impact claim was confirmed (glob/grep + result) — for any function-signature, schema-field, or shared-constant change, the Verified entry must enumerate every call site found, not just confirm "file exists". Template:

   | File | Change Type | Reason | Verified |
   |---|---|---|---|
   | src/foo.py | modify | adds method bar() | glob confirmed (12 lines, 3 callers grep'd) |
   | src/api.ts | extend | new route /widgets | grep'd routes table (1 caller updated) |
   

5. New Components — description of each new file/module/entity being introduced

6. Design Decisions — one paragraph per decision with rationale and alternatives considered

7. Build Steps — ordered list in /build-phase-compatible format:

   ### Step N: <name>
   - **Problem:** <what to build or fix — this becomes the --problem arg>
   - **Type:** code | operator | wait | conditional   (default "code", omit if code)
   - **Condition:**    (required when Type: conditional — see below)
     # (leave blank — created later by /repo-init or /repo-sync)
     
     
     
     
   

Quality bar before saving

Before writing the file, verify:

• Every "X or Y" choice from the conversation is resolved to a single answer.

• Impact analysis matches actual files in the codebase. For each function signature, schema field, or shared constant being changed, grep all call sites and list each one in the Impact Analysis table's Verified column — not just "probably only file X uses this." See feedback_grep_all_downstream_when_fixing_key_shape.md.

• Build steps are ordered so each step can be tested independently.

• A fresh model with no conversation history could read this plan and start building.

• If the feature touches autonomous, scheduled, background, or "always-on" behavior — OR if it adds observability infrastructure (dashboard, alerts, monitoring) for any such behavior in the existing project — the Build Steps include at least one step dedicated to running the full system end-to-end with realistic inputs and observing it long enough to expose time-dependent failures. If the build steps are all component-implementation work, surface this as a follow-up phase / step and add it before saving. Unit tests on each component are not enough for systems whose value depends on running unattended. "Background" here means runs unattended over wall-clock time (a daemon, scheduled job, soak loop, always-on watcher) — NOT parallel workers (threads, processes, async tasks) within a single user-invoked CLI run or HTTP request that completes and returns. When the feature is a one-shot invocation, state explicitly in the plan that the autonomous-behavior trigger does not fire so reviewers can confirm the classification.

• If the feature touches a data pipeline (producer → consumer chains, schema-bound storage, env→model→storage flows, or any "the dimensions/shape/columns must agree across modules" coupling), the Build Steps include at least one explicit smoke-gate step BEFORE any long-running observation step. A smoke gate is a 60-second end-to-end run with REAL components wired together (no mocks), exercised just enough to surface producer/consumer drift. Unit tests with mocks miss this entire class of bug because each test mocks the boundary it would have asserted on. Common shapes: "start the service, send 1 real request, assert no exception"; "open the SQLite DB, write 1 row with the latest schema, read it back"; "instantiate the model with the env's spaces, run 1 forward pass." Mark with Type: operator if it requires manual setup, otherwise Type: code. The smoke gate's deliverable is "the pipeline can complete one real cycle without crashing" — pass/fail of any business logic is out of scope.

• No Type: operator step has a code-shaped Produces: field, and no step has an operator-review . Both must be split per Phase 5's rule + split-pattern fence BEFORE mints issues.

Run /plan-wrap on the draft before saving if any of the above is uncertain.

File naming

Use a URL-friendly slug derived from the feature name:

• documentation/plugin-parsers-plan.md
• documentation/oauth-integration-plan.md
• documentation/batch-export-plan.md

If documentation/ doesn't exist, create it.