plan

# Plan

Produce implementation plans grounded in project principles. Write plans to `brain/plans/`. **Do NOT implement anything — the plan is the deliverable.**

**Use Tasks to track progress.** Create a task for each step (TaskCreate), mark each in_progress when starting and completed when done (TaskUpdate). Check TaskList after completing each step.

## Step 0 — Triage Complexity

Before running the full planning workflow, assess whether this task actually needs a plan:

**Trivially small (1–2 files, obvious approach):**
Tell the user this task doesn't need a plan and suggest implementing directly without the plan skill. **Stop here — do not implement.**

**Needs planning (proceed to Step 1):**
- The change spans 3+ files or introduces new architecture
- There are multiple valid approaches and the user should weigh in
- The task has unclear scope or cross-cutting concerns
- The user explicitly asks for a plan

## Step 1 — Load Principles

Read `brain/principles.md`. Follow every `[[wikilink]]` and read each linked principle file. These principles govern all plan decisions — refer back to them throughout.

**Do NOT skip this. Do NOT use memorized principle content — always read fresh.**

## Step 2 — Define Scope and Constraints

Use `AskUserQuestion` to resolve ambiguity before exploring the codebase:

- What is in scope vs explicitly out of scope?
- Are there constraints (dependencies, platform requirements, existing patterns to preserve)?
- What does "done" look like?

Frame questions with concrete options. If the request is already clear, confirm scope boundaries briefly and move on.

## Step 3 — Explore Context with Subagents

**Always** delegate exploration to subagents via the `Task` tool. Never do large-scale codebase exploration in the main context.

Spawn exploration agents (subagent_type: `Explore`) to:
- Read existing code in affected areas
- Identify patterns, conventions, and dependencies
- Map architecture relevant to the change
- Find tests, types, and related infrastructure

Run multiple agents in parallel when investigating independent areas.

## Step 4 — Gather Domain Skills

Check installed skills (`.agents/skills/`, `.claude/skills/`) for any that match the plan's domain. **Invoke matched skills** — read their output and incorporate domain guidance into the plan.

If the plan touches a domain **not covered** by installed skills, use `find-skills` to search for a relevant skill. If one is found, install it (project-local) and incorporate its guidance. Note what was installed so the user can see it. After the plan is written, delete any one-off skills that won't be needed again.

## Step 5 — Write the Plan

Create the plan directory and files manually:

1. Create `brain/plans/NN-slug-name/overview.md` (or a single file for simple plans)
2. Create phase files as needed
3. Update `brain/plans/index.md` with a link to the new plan

### Phase sizing

- **1 function/type + tests** per phase, or **1 bug fix** — not "one file" or "one component" (too variable)
- **Max 2-3 files touched** per phase when possible
- **Prefer 8-10 small phases** over 3-4 large ones — small phases keep future options open
- If a phase lists >5 test cases or >3 functions, split it

For small plans, a single file at `brain/plans/NN-plan-name.md` is fine.

For plans with 3+ phases, create a directory:

```
brain/plans/42-mvp/
├── overview.md
├── phase-1-scaffold.md
├── phase-2-layout.md
├── phase-3-drawing.md
└── testing.md
```

Non-phase files (like `testing.md`) are fine alongside phases.

### Overview file

Must include:
- **Context** — what problem this solves and why
- **Scope** — what's included, what's explicitly excluded
- **Constraints** — technical, platform, dependency, or pattern constraints
- **Applicable skills** — domain skills from Step 4 (list by name so implementers invoke them)
- **Phases** — ordered links to phase files: `[[plans/42-mvp/phase-1-scaffold]]`
- **Verification** — project-level verification commands

### Phase files

Each phase file must include:
- Back-link: `Back to [[plans/42-mvp/overview]]`
- **Goal** — what this phase accomplishes
- **Changes** — which files are affected and what changes, described at a high level
- **Data structures** — name the key types/schemas before logic, but a one-line sketch is enough — don't write full definitions
- **Verification** — static and runtime checks for this phase (see Step 6)

**Keep plans high-level.** Describe *what* and *why*, not *how* at the code level. A phase should read like a brief to a senior engineer: goals, boundaries, key types, and verification — not code snippets or pseudocode.

Order phases per the sequencing principle: infrastructure and shared types first, features after. Each phase should be independently shippable.

**Skill changes:** If a phase involves creating or updating a skill (any file in `.claude/skills/` or `.agents/skills/`), the phase must instruct the implementer to use the `skill-creator` skill during that phase.

### Redesign check

For changes touching existing code, apply redesign-from-first-principles:
> "If we were building this from scratch with this requirement, what would we build?"

Don't bolt changes onto existing designs — redesign holistically.

### Alternatives check

For architectural decisions, briefly sketch 2-3 approaches in the overview's Constraints section. State which was chosen and why. This prevents premature commitment and documents the design space explored.

## Step 6 — Verification Strategy

Every phase **must** have a verification section with both:

### Static
- Type checking passes
- Linting passes
- Code follows project conventions
- Tests written and passing

### Runtime
- What to test manually (launch the app, exercise the feature path)
- What automated tests to write (unit, integration, e2e)
- Edge cases to cover
- For UI: visual verification via screenshot

Per prove-it-works: "it compiles" is not verification. Every phase must describe how to **prove** the change works.

## Step 7 — Update Plans Index

Update `brain/plans/index.md` with a wikilink to the new plan's overview.

Do NOT edit `brain/index.md` — the auto-index hook maintains it automatically.

## Step 8 — Present to User

Summarize the plan: list the phases, scope boundaries, applicable skills, and verification approach. Ask the user to review the plan files in `brain/plans/`.

**Stop here.** Do not begin implementation. The user decides when and how to execute the plan.