---
name: plan
description: >-
  Systematic planning for medium-to-large tasks. Gathers context, identifies domain skills,
  writes phased plans to brain/plans/. Does NOT implement. Use for new features, multi-file
  refactors, or architectural changes — not small fixes. Triggers: "plan this", "break this down".
schedule: "When backlog items are tagged #needs_plan and have no linked plan yet"
---

# Plan

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

## Autonomous Session Mode

When this skill runs in a non-interactive Noodle execution session (for example `Cook`, `Oops`, or `Repair`):

- **Skip Step 2** (AskUserQuestion) — the scope is fully defined in the initial prompt.
- **Skip Step 6's pause** — write the plan, commit it, emit `stage_yield` (see Step 6), and end the session. Do not wait for human review.
- **Step 4** (find-skills) — install skills autonomously without confirmation.

All other steps proceed normally.

**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 — cite them by name in the plan overview and phase files.

**Do NOT skip this. Do NOT use memorized principle content — always read fresh.** The self-check in Step 5b will verify citations exist.

## 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. For large explorations, use a team.

## Step 4 — Gather Domain Skills

Match installed skills and discover missing ones. See `references/domain-skills.md` for the routing table and discovery workflow.

## Step 5 — Write the Plan

Create the plan using file tools. See `references/templates.md` for the full directory structure, overview/phase file formats, verification strategy, and CLI scaffolding steps.

### 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

### 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. See `brain/principles/exhaust-the-design-space.md`.

### Update plans index and todos

Verify both entries exist after writing the plan:
- `brain/plans/index.md` has `- [[plans/NN-plan-name/overview]]`
- `brain/todos.md` has the plan wikilink on the todo item

New todo: read `<!-- next-id: N -->`, append `N. [ ] description [[plans/NN-plan-name/overview]]`, increment next-id. Do NOT edit `brain/index.md` — the auto-index hook maintains it.

### Archiving completed plans

Move directory to `brain/archive/plans/`, update `brain/plans/index.md`, mark todo done via the `todo` skill.

## Step 5b — Self-Check

After writing all plan files, verify these three constraints before proceeding. Fix any violations before moving on.

**Principles cited:** The overview must reference at least 2 brain principles by `[[wikilink]]`. If not, re-read `brain/principles.md` and add the most relevant ones to the overview's design decisions.

**Phase sizing:** Review each phase. If any phase touches >3 files or lists >5 test cases, split it into smaller phases. Count the files listed under "Changes" — if the list exceeds 3, the phase is too big.

**No code in phases:** Phase files must not contain Go/TS/Python code blocks. Name types and functions but do not define them. A phase should read like a brief to a senior engineer, not a diff or implementation spec. If you find code blocks, replace them with prose describing the intended shape.

## Step 6 — Present and Yield

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

**Emit `stage_yield`** to signal the deliverable is complete:

```bash
noodle event emit --session $NOODLE_SESSION_ID stage_yield --payload '{"message": "Plan written to brain/plans/NN-slug-name/overview.md"}'
```

This tells the Noodle backend the stage's work is done, even if the agent process hasn't exited yet. Without this, the stage only completes on clean process exit.

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