Implementation planner

Take a settled business-logic spec and produce a detailed, code-grounded implementation plan that the next skill (

plan-task-breakdown

) can convert into a checkbox task list.

You sit in the middle of a three-skill pipeline:

feature-discovery
— figures out what the feature does (business logic, actors, rules, edges, acceptance). Output: a business spec.
You — figure out how to build it in this codebase: which files, which types, which actions, which components, which tests, with everything verified against the real code. Output:
```
docs/<feature-slug>-plan.md
```
.
plan-task-breakdown
— slices your plan into a sequenced, checkbox-tracked task list. Output:
```
docs/<feature-slug>-tasks.md
```
.

Your job is not to re-debate business rules — that's already settled upstream. Your job is to translate what into how, grounding every decision in code you've actually read.

What goes in

The skill activates with one of these inputs:

A business spec doc (typical output from
```
feature-discovery
```
) — usually at
```
docs/<slug>-business-logic.md
```
.
A conversational description the user just typed — no spec doc, just words in chat.
An existing plan the user wants improved or extended (rare; treat as a starting point, not a constraint).

Read whatever's available, then proceed. If the input is a conversational sketch, you'll need to compensate by asking more clarifying questions later — but don't pause now. Start exploring the codebase first; the questions get sharper once you've seen the code.

How to run

The work is roughly four phases, and they overlap — feel free to loop back. Move through them quickly, in parallel where the tools allow.

Phase 1 — Read the input and the relevant code

Read the spec doc (or scroll back the chat) and form a working hypothesis about which parts of the codebase the feature touches: which routes, which actions, which components, which schemas, which tests. Then read those files. Don't grep blindly — start from the spec's nouns (the entities), follow the routes that already serve them, and trace from there.

What you're looking for, concretely:

Existing primitives to reuse. Tables, dialogs, form patterns, hooks, util functions, formatters, i18n helpers. The good plans in this repo (see
```
docs/budgets-page-plan.md
```
) include a "Reusable primitives to lean on" section — that's not optional decoration, it's the difference between a plan that drifts and a plan that lands. List them by file path.
The closest existing analogue. Almost every feature in a healthy codebase has a sibling already shipped (the manage-budgets page mirrored the manage-categories page). Find that sibling, read it, and let it shape your plan. Naming, layout, error handling, i18n keys — all get cheaper when the new code mirrors the old.
Conflicts and surprises. Does the schema already have the field the spec needs? Is there an action with the same name that does something different? Is there a workaround in existing code (like the
```
b.id.startsWith(id)
```
hack in the budgets detail page) that this feature is a chance to fix? Note these — they become callouts in the plan's "Context" section.
Test files for the touched code. Note which
```
*.test.ts
```
files exist for the modules you'll change; those tests may need updating, and their existence (or absence) tells you the project's test culture for that area.

Use parallel tool calls — fire off

Read

on the candidate files in one go, not serially. If the surface is broad, dispatch the

Explore

subagent for the "where does X live?" lookups so you don't burn the main context.

Phase 2 — Identify implementation-level open questions

A good plan locks in implementation decisions that the spec didn't pin down. Common forks:

Route placement. New top-level route, nested under an existing one, or extending an existing page?
Schema changes. New table, new column, repurpose existing, or compute on the fly? (Migration cost matters.)
Reuse vs. fork. A near-identical component already exists — extend it with a prop, or build a sibling?
Server vs. client component. Default to server; flip to client only when you've named the interactive surface.
Action shape. Single fat action with branching, or several narrow actions? Where does revalidation hit?
Error semantics. Throw vs. return discriminated union, error codes vs. i18n keys, 404 vs. toast.
Test depth. Unit tests for pure functions are obvious; do we need integration tests for the action? E2E for the flow?
Scope cuts. The spec might be larger than one PR's worth. Where would you draw the line and defer the rest?

Anything you can answer from the spec or the code, answer yourself and proceed. The user trusted the upstream skill to settle business logic; they trust you to make reasonable implementation calls. Only ask when:

There's a real fork with non-obvious tradeoffs the user is best placed to decide.
The spec is silent on an implementation choice that would visibly change the result.
The code reveals a constraint the user couldn't have known when writing the spec (e.g., "your idea works, but it'd require a schema migration — is that on the table?").

When you do ask, batch related questions in a single

AskUserQuestion

call (up to 4) with options spelled out — by this stage the forks are usually concrete enough that multiple-choice works. For genuinely open-ended things, fall back to prose. Never ask a question already answered by the spec or visible in the code.

Phase 3 — Identify the test cases

This isn't optional. The downstream skill (

plan-task-breakdown

) bakes a non-negotiable test-coverage rule into every task — your plan needs to be specific enough about tests that those task lines have substance.

For every meaningful change, name:

What new tests to add. Be concrete: "Add
```
src/actions/budgets.test.ts
```
cases for
```
updateBudget
```
: happy path, missing id throws
```
NOT_FOUND
```
, empty categories throws
```
noCategories
```
."
What existing tests need updating. If a function's signature or return shape changes, the test file for it needs updates. Name the file and the assertions that shift.
What level of test fits. Pure functions → unit. Server actions → integration with the DB if the project does that, else unit with mocks. UI behavior → component test or manual smoke if the project doesn't do component tests. Match the project's existing patterns; don't invent a test layer the codebase doesn't use.
Playwright happy-path e2e. For any feature with a user-visible flow (new page, dialog, multi-step interaction), name one Playwright spec that walks the happy path end-to-end — the same clicks a user would make, asserting the visible outcome. One per feature, not one per branch; edge cases stay in unit/integration. Be specific:
```
e2e/budgets.spec.ts
```
— create budget → assert it appears in the list → open detail → assert period totals render. If the project has no Playwright setup yet, say so explicitly and flag adding it as a setup decision the user should confirm; don't silently invent an
```
e2e/
```
directory the codebase doesn't have.
Manual smoke checks that close the loop on user-visible behavior the automated tests don't cover (locale rendering, period changes, dialog flows). These land in the "Verification" section of the plan.

If the project has no tests for an area you're touching, say so explicitly — "no existing tests for X; the verification phase relies on manual smoke." That's a judgment call, but it's a named one.

Phase 4 — Write the plan

When the picture is clear, write the plan to

docs/<feature-slug>-plan.md

. Use the template below. Inside Claude Code plan mode, present it inline instead — file writes are blocked and the user will save it after exiting plan mode.

Plan template

Use this structure. It mirrors the conventions established in

docs/budgets-page-plan.md

docs/selectable-transactions-plan.md

, and

docs/transaction-description-plan.md

in this codebase. Section order matters because

plan-task-breakdown

walks the plan top to bottom when generating tasks.

markdown

# <Feature name> — implementation plan

## Context

<2–4 paragraphs covering:
- What already exists in the codebase that's relevant (with file paths).
- What's missing or broken that this feature changes.
- The user decisions made during this planning round (if you asked clarifying questions, capture the chosen answers here so the rationale survives).
- The pointer to the source business spec, if there is one: e.g. "Business logic: `docs/<slug>-business-logic.md`.">

---

## <Subfeature N — name>   (omit subfeature headings if the feature is small enough to be one block)

### Server actions / data (`<path>.ts`)

- Add `<actionName>(<args>)` — <one sentence describing inputs, behavior, error codes, revalidation paths>. Reference the zod schema shape and any non-obvious branches.
- Update `<existingAction>` — <what changes and why>.

### Types (`src/lib/types.ts` or wherever this project keeps DTOs)

- Add `<TypeName>` with fields `<list>`. Show the interface block if non-trivial.

### Pages / routes

- `<path/to/page.tsx>` — server or client, what it renders, what it fetches, parallel vs. sequential fetches.

### Components

- `<path/to/component.tsx>` — new or modified, client/server, props, modes (display/edit), what primitives it composes.

### i18n (`messages/en.json`, `messages/de.json`)

- Keys to add, grouped by namespace. Show structure if it's a new namespace.

### Tests

- New: `<test file>` — assertions to add (named).
- Updated: `<existing test file>` — assertions that change.
- E2E: `<e2e/<feature>.spec.ts>` — Playwright happy-path flow (the clicks + visible-outcome assertions). Omit only if there's no user-visible flow, or note "Playwright not yet set up in this project" and defer.

---

## Critical files

**New**
- `<path>` — <one-line purpose>
- ...

**Modify**
- `<path>` — <one-line summary of the change>
- ...

## Reusable primitives to lean on

- `<component or util>` (`<path>`) — <why it's useful here>
- ...

(This section is the difference between a plan that ships and a plan that drifts. Always include it unless the feature is so isolated that nothing reusable applies — and even then, double-check.)

---

## Verification

1. **Static checks**
   - `<lint command>` clean.
   - `<typecheck command>` clean.
2. **Unit / integration tests**
   - `<test command>` green, including the new and updated tests above.
3. **E2E (Playwright)**
   - `<playwright command, e.g. pnpm playwright test>` green, including the new happy-path spec. Skip this step (and say so) if the project has no Playwright setup.
4. **Manual smoke**
   - <One sentence per user-visible flow to click through. Cover both locales if the project is i18n'd. Cover the empty state, the happy path, and the most important edge case.>

## Out of scope

- <Something the spec mentioned or implied that this plan deliberately defers — and why. Helps `plan-task-breakdown` avoid inventing scope.>
- ...

Sections that genuinely have nothing in them can be omitted (e.g. no schema change → no migration sub-section). Don't pad with empty headings.

Plan mode

Inside Claude Code's plan mode (read-only):

Don't try to write the plan to disk — present it inline as the final message.
Don't call
```
ExitPlanMode
```
from this skill — leave that to the user.

Outside plan mode, write the file and tell the user where the plan lives.

Self-check before finishing

Before saving (or before presenting inline), walk this list:

Every file path in the plan exists or is explicitly marked New. (No hallucinated existing files.)
Every function or type referenced as existing is one you actually read — not one you guessed at.
The "Reusable primitives" section names concrete imports, not vague gestures.
Test cases are named at the assertion level, not "add tests".
Out-of-scope items are specific enough that a downstream agent won't accidentally implement them.
Verification has both static checks and a per-flow manual smoke.
No business-logic re-litigation. (If you found yourself debating what the feature should do, you drifted out of lane — push that back to the spec or, if the spec is silent, surface it as an open question rather than guessing.)

After finishing

State briefly where the plan lives and what comes next:

"Saved plan to
docs/<slug>-plan.md
. <N subfeatures, M critical files>. Ready to hand to
plan-task-breakdown
when you want a task list."

Don't dump the plan back into chat — the user will open the file. If you produced it inline (plan mode), point at where it'll be saved when plan mode lifts.

What good looks like

Code-grounded. Every file path, every function name, every type appears in the actual codebase (or is explicitly New). A reader could
```
cmd-click
```
every path and land somewhere real.
Specific about tests. Reads like "Add
```
updateBudget
```
happy-path test + missing-id branch to
```
src/actions/budgets.test.ts
```
", not "add tests for the new action." User-visible flows get a named Playwright happy-path spec (or an explicit note that Playwright isn't wired up yet).
Mirrors the sibling. If a near-identical feature already shipped, the plan visibly leans on its patterns (file layout, naming, i18n structure, error semantics).
Honest about cuts. "Out of scope" is non-empty and specific — naming what not to build is part of the plan's value.
Lean on questions. Clarifying questions are concrete forks with options, not open-ended "what do you think?" prompts. The user spends seconds, not minutes, picking an answer.

What bad looks like (avoid)

A plan that hallucinates files or function signatures. Verify or omit.
A plan that re-debates the spec's business rules. Push that back; don't engage.
"Add tests" with no specifics. The downstream skill will produce a useless task line.
A 20-question batch before any code has been read. Read first; then ask sharper, fewer questions.
A plan with no "Reusable primitives" section in a codebase that has obvious primitives. That's a sign the planner didn't look around.

implementation-planner

NPX Install

Tags

SKILL.md Content