Produce an implementation plan for the task in $ARGUMENTS, grounded in this codebase's real files and conventions. Plan only — do not write, edit, or run implementation code.
If $ARGUMENTS is empty, ask the user what to plan and stop. Do not invent a task.
Investigate first (internal prep — do not emit this section)
Do not plan from assumptions — read before you write.
- Locate the relevant code: grep/glob for the feature's entry points, the modules it touches, and the nearest existing feature that resembles this one. Read those files, not just their names.
- Detect the stack and its conventions from what's there: language, framework, how modules are structured, how state/data flows, the test runner and test file layout, lint/format config, error-handling and logging patterns. The plan must follow these, not impose new ones.
- Identify integration points the change must respect: public APIs, DB schema/migrations, shared types, config/env, feature flags, callers of any function you'd change.
Emit the plan as exactly these sections, in this order
Task & acceptance criteria
This is the first thing the reader sees — surface it, don't keep it in your head. Restate the task in one sentence, then list the acceptance criteria you infer as a bulleted checklist.
Steps
An ordered list of small steps, each independently implementable and verifiable — the kind you could land as one focused commit. For every step give:
- What it does, in one line.
- Files/areas it touches, by real path (use the paths you found, not placeholders).
- How to verify it: the exact command to run (existing test, new test to add, typecheck, lint, manual check) and the observable pass condition.
Order steps so the codebase stays working after each: schema/types and shared utilities before the code that uses them; wiring and callers before UI; tests alongside the code they cover. Prefer the smallest change that satisfies the criteria — reuse existing helpers and patterns over new abstractions, and name which existing thing you're reusing.
Risks & unknowns
What could break, what you couldn't confirm from the code, and the assumptions the plan rests on.
Open questions
Clarifications you need from the user before this plan is safe to execute: an ambiguous acceptance criterion, an unstated requirement, intent only they know. These are blocking — you lack a fact only the user can supply. If none, write "None."
Decisions for a human
Choices where you already have the facts but the tradeoff is a judgment call (library, API shape, migration strategy). Lay out each option with its cost and recommend one; do not silently pick. Unlike an open question, nothing here blocks you from writing the plan — you can proceed on your recommendation if the human stays silent. If none, write "None."
Out of scope
Adjacent things you are deliberately not doing, so the boundary is explicit.
Rules
- Never modify files, run implementation code, or install packages — this is a planning step. Read-only exploration and running existing tests to understand current behavior are fine.
- Every step must name concrete files and a concrete verification. Cut any step you can't ground that way.
- No filler. If part of the task is trivial, say so in one line and move on; spend the detail where the risk is.
- If the task is too large for one plan, split the Steps section into phases that each ship independently and say which phase to start with.