plan

name	plan
description	Use when a task is multi-step, ambiguous, or high-impact and you need an executable implementation plan before editing code.
argument-hint	["task description"]

task = $ARGUMENTS

Produce the minimum artifact that prevents the executor from going wrong. The executor starts with an empty context window: they get this plan and the codebase, nothing else. Every ambiguity becomes a wrong guess they make confidently.

Match depth to complexity. A 3-file bug fix needs a paragraph, not a document. If you could describe the diff in one sentence, skip the plan entirely.

Exploration

Explore until you can articulate why one approach beats alternatives — then stop and write. If you can't articulate the tradeoffs, you haven't explored enough. If you're still reading files after the picture is clear, you've explored too much. External-axis stop: a borrowable pattern is identified, or you've confirmed nobody solved it cleanly — inventing is the fallback, not the default.

Two axes, pursued concurrently via read-only subagents that return summaries (not raw file dumps):

• Codebase — existing implementations, patterns, conventions. For every new pattern the plan introduces, cite the precedent file:line the executor should mirror. Without the citation, the executor will reinvent — even when the precedent exists.
• External — web search for how others solved this. Libraries, vendor docs, open-source implementations. Prefer borrowing a named approach over inventing; name the source (URL or library) in the plan.

Decomposition

Choose based on task shape, not habit. Default to vertical slice; switch when the task clearly fits another:

Strategy	When	Risk it mitigates
Vertical slice	Multiple independent behaviors	Integration surprises — each slice proves end-to-end
Walking skeleton	Uncertain integration path	Late-stage "it doesn't connect" — proves wiring first
Layer-by-layer	Clear layers, different complexity zones	Allows parallel work; natural when data model drives everything

Specificity

The hard part of planning is identifying the surface of change — which files, which functions, which call sites. Once the surface is named, the edits are obvious. Name concrete files and functions; describe what changes and why; reference precedent for the pattern to follow. Leave how to the executor — they need goals and constraints, not pseudocode.

When a step would otherwise contain a guess, ask the user before saving. The plan is a closed contract — the executor cannot resolve ambiguity, only act on it.

• Under-specified: Add a rate limiter to the API.
• Over-specified: Pseudocode of the rate-limit check, variable names, HTTP status codes.
• Calibrated: Add per-user rate limiting to authenticated endpoints. New middleware in src/api/middleware/ratelimit.py following the pattern of src/api/middleware/auth.py (middleware class + decorator registration in src/api/app.py:42). Use the existing Redis client from src/infra/redis.py.

Litmus tests:

• "Could the executor start in the wrong file?" → be more specific.
• "Could the executor implement this without reading my plan?" → the step is too detailed.

Plan Format

Required:

• Goal — One sentence. What exists after that didn't before.
• Files — Exact paths with [NEW]/[MOD]/[DEL] prefix. Map the change surface before decomposing into steps.
• Steps — Ordered, checkboxed (- [ ]), each naming the file(s) it touches.
• Verification — Per-step: command + expected result. Final: acceptance criteria the executor checks before declaring done.

Add when the task warrants:

• Background — The why, when not obvious from the goal.
• Key Concepts — Domain terms, sentinel values, non-obvious patterns. Table format.
• Approach & Rejected Alternatives — What you chose and rejected, with rationale. Prevents re-litigating decisions.
• Edge Cases — The 3–5 most likely failure modes and how the plan handles each. If you can't name them, you haven't understood the problem deeply enough.
• Risks — Only non-obvious ones with mitigations.
• Work Decomposition — For parallel execution (Workflow tool or subagents): which steps run in parallel vs. sequential, and why.

No placeholders survive to save: no TBD, no "add error handling" without specifics, no open questions. Every ambiguity was resolved with the user first — the saved plan is a closed contract.

Save & Handoff

Save to docs/plans/<type>-<short-name>.md (adapt to project conventions if established). Types: feat-, fix-, refactor-, chore-.

To update an existing plan, re-read it, diff against new requirements, and revise in place.

Hand off to the Workflow tool (or parallel subagents) for parallel work, or implement directly for single-agent execution.