/plan

This skill is self-contained — follow the steps below instead of delegating to external planning skills (superpowers, etc.).

# /plan

This skill is self-contained — follow the steps below instead of delegating to external planning skills (superpowers, etc.).

Research the codebase and create a spec + phased implementation plan. Zero interactive questions — explores the code instead.

## When to use

Creates a track for any feature, bug fix, or refactor with a concrete, file-level implementation plan. Works with or without `/setup`.

## MCP Tools (use if available)

- `session_search(query)` — find similar past work in Claude Code chat history
- `project_code_search(query, project)` — find reusable code across projects
- `codegraph_query(query)` — check dependencies of affected files
- `codegraph_explain(project)` — architecture overview: stack, languages, directory layers, key patterns, top dependencies, hub files
- `kb_search(query)` — search knowledge base for relevant methodology

If MCP tools are not available, fall back to Glob + Grep + Read.

## Steps

1. **Parse task description** from `$ARGUMENTS`.
   - If empty, ask via AskUserQuestion: "What feature, bug, or refactor do you want to plan?"
   - This is the ONE question maximum.

2. **Detect context** — determine where plan files should be stored:

   **Project context** (normal project with code):
   - Detected by: `package.json`, `pyproject.toml`, `Cargo.toml`, `*.xcodeproj`, or `build.gradle.kts` exists in working directory
   - Plan path: `docs/plan/{trackId}/`

   **Knowledge base context** (documentation-centric project):
   - Detected by: NO package manifest found, BUT directories like `docs/`, `notes/`, or structured numbered directories exist
   - Plan path: `docs/plan/{shortname}/`
   - Note: the shortname is derived from the task (kebab-case, no date suffix for the directory)

   Set `$PLAN_ROOT` based on detected context. All subsequent file paths use `$PLAN_ROOT`.

3. **Load project context** (parallel reads):
   - `CLAUDE.md` — architecture, constraints, Do/Don't
   - `docs/prd.md` — what the product does (if exists)
   - `docs/workflow.md` — TDD policy, commit strategy (if exists)
   - `package.json` or `pyproject.toml` — stack, versions, deps

3. **Auto-classify track type** from keywords in task description:
   - Contains "fix", "bug", "broken", "error", "crash" → `bug`
   - Contains "refactor", "cleanup", "reorganize", "migrate" → `refactor`
   - Contains "update", "upgrade", "bump" → `chore`
   - Default → `feature`

4. **Research phase** — explore the codebase to understand what needs to change:

   a. **Get architecture overview** (if MCP available — do this FIRST):
      ```
      codegraph_explain(project="{project name from CLAUDE.md or directory name}")
      ```
      Gives you: stack, languages, directory layers, key patterns, top dependencies, hub files.

   b. **Get RepoMap** (if MCP available):
      ```
      codegraph_repomap(project="{project name from CLAUDE.md or directory name}")
      ```
      Gives you a YAML map of the most important files and their exported symbols (classes/functions).

   c. **Find relevant files** — Glob + Grep for patterns related to the task:
      - Search for keywords from the task description
      - Look at directory structure to understand architecture
      - Identify files that will need modification

   d. **Precedent retrieval** (context graph pattern — search past solutions BEFORE planning):
      - Search past sessions (if MCP available):
        ```
        session_search(query="{task description keywords}")
        ```
        Look for: how similar tasks were solved, what went wrong, what patterns worked.
      - Search KB for relevant methodology:
        ```
        kb_search(query="{task type}: {keywords}")
        ```
        Check for: harness patterns, architectural constraints, quality scores.

   e. **Search code across projects** (if MCP available):
      ```
      project_code_search(query="{relevant pattern}")
      ```

   f. **Check dependencies** of affected files (if MCP available):
      ```
      codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
      ```

   g. **Read existing tests** in the affected area — understand testing patterns used.

   h. **Read CLAUDE.md** architecture constraints — understand boundaries and conventions.
      - Check for harness section: module boundaries, data validation rules, lint configs.
      - Read `docs/ARCHITECTURE.md` and `docs/QUALITY_SCORE.md` if they exist.

   i. **Detect deploy infrastructure** — search for deploy scripts/configs to include deploy phase in plan:
      ```bash
      find . -maxdepth 3 \( -name 'deploy.sh' -o -name 'Dockerfile' -o -name 'docker-compose.yml' -o -name 'wrangler.toml' -o -name 'sst.config.ts' \) -type f 2>/dev/null
      ```
      If found, read them to understand deploy targets. Include a deploy phase in the plan with concrete commands.

5. **Detect overlapping plans** — before creating a new track, check for existing plans that cover similar scope:

   ```bash
   ls docs/plan/*/plan.md docs/plan/*/spec.md 2>/dev/null
   ```

   For each existing plan found:
   - Read its `spec.md` Summary and Acceptance Criteria
   - Compare scope with the new task description
   - Check if tasks overlap (>50% of files or acceptance criteria in common)

   **If overlap detected:**
   - If existing plan is incomplete (`[ ]` tasks remain): recommend extending it instead of creating a new track. Show the user: "Existing track `{trackId}` covers similar scope ({overlap description}). Extend it or create a separate track?"
   - If existing plan is complete (`[x]` all tasks): proceed with new track but reference the prior track in spec.md Dependencies
   - If multiple existing plans overlap with each other: recommend consolidating them into one track before proceeding

   **If no overlap:** proceed normally.

6. **Generate track ID:**
   - Extract a short name (2-3 words, kebab-case) from task description.
   - Format: `{shortname}_{YYYYMMDD}` (e.g., `user-auth_20260209`).

7. **Create track directory:**
   ```bash
   mkdir -p $PLAN_ROOT
   ```
   - Project context: `docs/plan/{trackId}/`
   - KB context: `docs/plan/{shortname}/`

8. **Generate `$PLAN_ROOT/spec.md`:**
   Based on research findings, NOT generic questions.
   ```markdown
   # Specification: {Title}

   **Track ID:** {trackId}
   **Type:** {Feature|Bug|Refactor|Chore}
   **Created:** {YYYY-MM-DD}
   **Status:** Draft

   ## Summary
   {1-2 paragraph description based on research}

   ## Acceptance Criteria
   - [ ] {concrete, testable criterion}
   - [ ] {concrete, testable criterion}
   {3-8 criteria based on research findings}

   ## Dependencies
   - {external deps, packages, other tracks}

   ## Out of Scope
   - {what this track does NOT cover}

   ## Technical Notes
   - {architecture decisions from research}
   - {relevant patterns found in codebase}
   - {reusable code from other projects}
   ```

9. **Generate `$PLAN_ROOT/plan.md`:**
   Concrete, file-level plan from research. Keep it tight: 2-4 phases, 5-15 tasks total.

   **Critical format rules** (parsed by `/build`):
   - Phase headers: `## Phase N: Name`
   - Tasks: `- [ ] Task N.Y: Description` (with period or detailed text)
   - Subtasks: indented `  - [ ] Subtask description`
   - All tasks use `[ ]` (unchecked), `[~]` (in progress), `[x]` (done)

   ```markdown
   # Implementation Plan: {Title}

   **Track ID:** {trackId}
   **Spec:** [spec.md](./spec.md)
   **Created:** {YYYY-MM-DD}
   **Status:** [ ] Not Started

   ## Overview
   {1-2 sentences on approach}

   ## Phase 1: {Name}
   {brief description of phase goal}

   ### Tasks
   - [ ] Task 1.1: {description with concrete file paths}
   - [ ] Task 1.2: {description}

   ### Verification
   - [ ] {what to check after this phase}

   ## Phase 2: {Name}
   ### Tasks
   - [ ] Task 2.1: {description}
   - [ ] Task 2.2: {description}

   ### Verification
   - [ ] {verification steps}

   {2-4 phases total}

   ## Phase {N-1}: Deploy (if deploy infrastructure exists)
   _Include this phase ONLY if the project has deploy scripts/configs (deploy.sh, Dockerfile, docker-compose.yml, wrangler.toml, sst.config.ts, vercel.json). Skip if no deploy infra found._

   ### Tasks
   - [ ] Task {N-1}.1: {concrete deploy step — e.g. "Run python/deploy.sh to push Docker image to VPS", "wrangler deploy", etc.}
   - [ ] Task {N-1}.2: Verify deployment — health check, logs, HTTP status

   ### Verification
   - [ ] Service is live and healthy
   - [ ] No runtime errors in production logs

   ## Phase {N}: Docs & Cleanup
   ### Tasks
   - [ ] Task {N}.1: Update CLAUDE.md with any new commands, architecture changes, or key files
   - [ ] Task {N}.2: Update README.md if public API or setup steps changed
   - [ ] Task {N}.3: Remove dead code — unused imports, orphaned files, stale exports

   ### Verification
   - [ ] CLAUDE.md reflects current project state
   - [ ] Linter clean, tests pass

   ## Final Verification
   - [ ] All acceptance criteria from spec met
   - [ ] Tests pass
   - [ ] Linter clean
   - [ ] Build succeeds
   - [ ] Documentation up to date

   ## Context Handoff
   _Summary for /build to load at session start — keeps context compact._

   ### Session Intent
   {1 sentence: what this track accomplishes}

   ### Key Files
   {list of files that will be modified, from research}

   ### Decisions Made
   {key architecture decisions from research phase — why X over Y}

   ### Risks
   {known risks or edge cases discovered during research}

   ---
   _Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._
   ```

   **Plan quality rules:**
   - Every task mentions specific file paths (from research).
   - Tasks are atomic — one commit each.
   - Phases are independently verifiable.
   - Total: 5-15 tasks (not 70).
   - **Last phase is always "Docs & Cleanup"**.
   - **Criteria-task coverage:** every acceptance criterion in spec.md MUST map to at least one task in plan.md. After generating both files, cross-check: list each criterion and verify a task addresses it. If a criterion has no corresponding task — add one. Uncovered criteria are the #1 cause of "plan complete but spec not met" failures.
   - **Harness-aware:** if the task introduces new patterns, include a task to update lint rules or CLAUDE.md constraints. If it touches module boundaries, include verification of dependency direction. Think: "what harness change prevents future agents from breaking this?"

10. **Create progress task list** for pipeline visibility:

   After writing plan.md, create TaskCreate entries so progress is trackable:
   - One task per phase: "Phase 1: {name}" with task list as description.
   - This gives the user and pipeline real-time visibility into what's planned.
   - `/build` will update these tasks as it works through them.

   If `superpowers:writing-plans` skill is available, follow its granularity format: bite-sized tasks (2-5 minutes each), complete code in task descriptions, exact file paths, verification steps per task. This enhances the built-in format above.

11. **Show plan for approval** via AskUserQuestion:
   Present the spec summary + plan overview. Options:
   - "Approve and start" — ready for `/build`
   - "Edit plan" — user wants to modify before implementing
   - "Cancel" — discard the track

   If "Edit plan": tell user to edit `$PLAN_ROOT/plan.md` manually, then run `/build`.

## Output

```
Track created: {trackId}

  Type:   {Feature|Bug|Refactor|Chore}
  Phases: {N}
  Tasks:  {N}
  Spec:   $PLAN_ROOT/spec.md
  Plan:   $PLAN_ROOT/plan.md

Research findings:
  - {key finding 1}
  - {key finding 2}
  - {reusable code found, if any}

Next: /build {trackId}
```

## Rationalizations Catalog

These thoughts mean STOP — you're skipping research:

| Thought | Reality |
|---------|---------|
| "I know this codebase" | You know what you've seen. Search for what you haven't. |
| "The plan is obvious" | Obvious plans miss edge cases. Research first. |
| "Let me just start coding" | 10 minutes of research prevents 2 hours of rework. |
| "This is a small feature" | Small features touch many files. Map the blast radius. |
| "I'll figure it out as I go" | That's not a plan. Write the file paths first. |
| "70 tasks should cover it" | 5-15 tasks. If you need more, split into tracks. |

## Compatibility Notes

- Plan format must match what `/build` parses: `## Phase N:`, `- [ ] Task N.Y:`.
- `/build` reads `docs/workflow.md` for TDD policy and commit strategy (if exists).
- If `docs/workflow.md` missing, `/build` uses sensible defaults (moderate TDD, conventional commits).

## Common Issues

### Plan has too many tasks
**Cause:** Feature scope too broad or tasks not atomic enough.
**Fix:** Target 5-15 tasks across 2-4 phases. Split large features into multiple tracks.

### Context detection wrong (project vs KB)
**Cause:** Directory has both code manifests and KB-style directories.
**Fix:** Project context takes priority if `package.json`/`pyproject.toml` exists.

### Research phase finds no relevant code
**Cause:** New project with minimal codebase or MCP tools unavailable.
**Fix:** Skill falls back to Glob + Grep. For new projects, the plan will rely more on CLAUDE.md architecture and stack conventions.