Task Decomposition Plans skill for Claude Code
Plans with checks, risk first, before a line of code. Stops Claude from diving into a large change and stalling halfway. It researches the code read-only in plan mode, asks only the questions that change the design, then writes a plan file with explicit non-goals, vertical milestones that each leave the system working, runnable acceptance checks, and checkpoints before anything irreversible. Execution follows the file, with statuses and decisions updated as it goes.
- name
task-decomposition-plans - size190 lines · ≈2,150 tokens
- files1
- licenseMIT
- updated
What Claude sees before loading it
This description is the only part of the skill that sits in context all the time. Claude reads it to decide when to load the full playbook below.
description: Turns a large or ambiguous coding request into a written plan before any code is changed, using Claude Code plan mode for read-only research, then producing milestones that each leave the system working, acceptance criteria as runnable checks, risk-first ordering, explicit non-goals, and user checkpoints, saved to a plan file and tracked during execution. Use when a request spans many files or days, requirements are vague, the user says "plan this first", "break this down", or "how should we approach", or work keeps stalling mid-implementation.Try asking
- Plan the move from REST polling to websockets before you change anything
- Break this multi-tenant billing feature into milestones I can review
- We keep getting stuck halfway through this refactor — make a real plan
Use it when
- The request spans many files, modules or days
- Requirements are vague or several designs are plausible
- The work includes migrations or other irreversible steps
- Previous attempts stalled mid-implementation
Skip it when
- The change is small and obvious — just make it
- You need to find out whether something is feasible at all — use technical-spike first
- You need hour and day estimates for stakeholders — use work-estimation instead
How to check the result
Each milestone in the plan ends with a runnable check, milestone one retires the top risk, and a fresh session can start it from the file without asking questions.
The common mistake it prevents
Planning in horizontal layers, all database then all API then all UI, so nothing works end to end until the final step exposes the integration problems.
A plan is good when someone else, or a fresh session, could execute it without asking what was meant: the goal and non-goals are explicit, the first milestone retires the biggest risk, every milestone leaves the system working and ends in a runnable check, and the points where the user must approve are marked. The plan lives in a file, not in the conversation.
Plan or just do it?
| Situation | Approach |
|---|---|
| One or two files, obvious change, clear request | Just do it; no plan file |
| Many files, unfamiliar code, or more than ~1 hour of work | Plan |
| Ambiguous requirements or several plausible designs | Plan, with questions first |
| Irreversible steps (data migration, public API change, deletion) | Plan, with a checkpoint before each |
| Exploratory “can we even do X?” | Time-boxed spike first (see technical-spike), then plan |
Workflow
- [ ] 1. Restate the goal; list ambiguities; ask only design-changing questions
- [ ] 2. Research read-only (plan mode) before proposing anything
- [ ] 3. Identify unknowns and risks
- [ ] 4. Decompose into milestones (vertical slices, risk first)
- [ ] 5. Write acceptance checks per milestone
- [ ] 6. Mark checkpoints and non-goals; write the plan file
- [ ] 7. Get approval; execute milestone by milestone, updating the file1. Restate and question
Write the goal in one sentence and the definition of done in one or two. List what is ambiguous. Ask the user at most 3-5 questions, and only ones whose answers change the design (“Should existing users be migrated or only new signups?”). For everything else, state the assumption in the plan so it can be corrected cheaply.
2. Research in plan mode
Plan mode keeps Claude read-only while it investigates and proposes. Enter it with
Shift+Tab (cycling modes) or start with claude --permission-mode plan. Investigate:
- Entry points and the data flow the change touches (
grep -rn, read callers). - Existing patterns to follow (how similar features are built and tested here).
- Test commands and current state (
pnpm testgreen before you start?). - Constraints: schema ownership, public APIs, feature flag system, deploy process.
Delegate wide searches to a subagent (built-in Explore) to keep the planning context
clean. Do not propose milestones before reading the code they touch.
3. Unknowns and risks
List each unknown with how it will be resolved. Rank by “how badly would this change the plan if it went the wrong way”. The highest-ranked unknown becomes milestone 1 or a spike before it. Typical ones: third-party API limits, performance at real data size, whether a library supports the needed feature, data quality in production.
4. Decompose
Rules for milestones:
- Vertical slices: each delivers a thin, working path end to end (DB -> API -> UI) rather than a horizontal layer. Integration problems surface in week one, not at the end.
- Always working: after each milestone, build and tests pass and the app runs. Unfinished features hide behind a flag.
- Reviewable size: roughly one PR, a few hundred lines of diff, a few hours of agent work. Split anything larger.
- Ordered by risk, then dependency: retire unknowns first; foundational changes (schema expand, shared types) before consumers.
- Steps inside a milestone are concrete enough to verify: “Add
GET /api/searchreturning top 20 by rank” not “implement search backend”.
Decomposition patterns:
| Work type | Shape |
|---|---|
| New feature | Walking skeleton behind a flag -> slice per user capability -> polish -> flag removal |
| Schema or data migration | Expand (add) -> dual write -> backfill -> switch reads -> contract (remove), checkpoint before backfill and contract |
| Large refactor | Characterization tests -> small behavior-preserving moves, each green -> delete old path |
| Bug in unfamiliar area | Reproduce as failing test -> locate -> fix -> regression guard (see systematic-debugging) |
| Performance work | Baseline measurement -> one change per milestone with before/after numbers |
| Integration with external service | Spike against sandbox -> client wrapper with tests -> feature wiring -> failure handling |
5. Acceptance checks
Every milestone ends with checks that can be run or observed, not opinions:
- Commands:
pnpm test --filter search,pnpm typecheck,curl -s localhost:3000/api/search?q=shoe | jq lengthreturns 20. - Behavior: “Given a logged-out user, when they search, then results show without prices.”
- Non-regression: “Existing checkout e2e suite still passes.”
- Numbers where relevant: “p95 under 200 ms on the 1M-row fixture.”
A milestone that cannot be checked is too vague. Rewrite it.
6. Checkpoints, non-goals, and the file
Mark user checkpoints:
- After the plan itself (approval before any code).
- After milestone 1 (does the skeleton match what they pictured?).
- Before anything irreversible or externally visible: migrations on shared data, API removals, production deploys, deleting code paths. Get explicit confirmation there.
Non-goals prevent scope creep and tell reviewers what is deliberately missing.
Save to docs/plans/<task>.md (committed, for team work) or .claude/plans/<task>.md
(personal). Template:
# Plan: Product search
Goal: Logged-in and anonymous users can search products by name and tag.
Done when: search page live behind `search_v1`, flag on in staging, e2e green.
Non-goals: typo tolerance, personalization, admin search (separate plan).
Assumptions: Postgres full-text is enough for 200k products (verify in M1).
## Risks / unknowns
1. FTS ranking quality on real product names -> M1 measures on staging data copy
2. Index build time on prod table -> M1 measures; CONCURRENTLY required
## Milestones
### M1: Skeleton + risk check [status: done | commit 4e1a9c2]
- Add tsvector column + GIN index (migration, CONCURRENTLY)
- `GET /api/search?q=` returns top 20 by ts_rank behind flag
- Check: `pnpm test --filter api search` green; ranking spot-check of 20 queries recorded below
- CHECKPOINT: review ranking results with user
### M2: Search page [status: in progress]
- Results page with empty/loading/error states; URL holds the query
- Check: e2e `search.spec.ts` green; Lighthouse a11y >= 95
### M3: Tags filter [status: todo]
- ...
### M4: Rollout [status: todo]
- CHECKPOINT before enabling flag in production
- Check: error rate and p95 unchanged 24 h after enabling
## Decisions log
- 2026-10-19: Postgres FTS over Meilisearch (M1 ranking acceptable; no new infra)7. Execute against the plan
- Work one milestone at a time. Mirror its steps in the in-session todo list.
- After each milestone: run its checks, commit, update the status line with the commit SHA, append decisions to the log.
- Re-plan (edit the file, tell the user) when: an assumption proves false, a milestone takes more than twice its expected effort, or a new requirement appears. Do not silently drift from the plan.
- Long work spanning sessions: the plan file plus a handoff note (see
session-handoff-notes) is the resume point after/clear.
Anti-patterns
- Horizontal plans (all models, then all endpoints, then all UI): nothing works until the end and integration surprises arrive last.
- A 40-step plan of trivial items; it hides the 3 decisions that matter.
- “Refactor everything first” milestones with no user-visible value and no checks.
- Planning before reading the code, then discovering the existing pattern mid-way.
- Plans that never mention tests or verification.
- Asking the user ten questions up front instead of stating assumptions.
Verification of the plan
Before asking for approval, confirm:
- Goal, done-when, and non-goals are each one or two lines and unambiguous.
- Milestone 1 addresses the top risk.
- Every milestone has at least one runnable check and leaves the system working.
- Every irreversible step has a checkpoint.
- A fresh session given only the file could start M1 without questions.
Output
Present the plan file path and a short summary:
**Plan:** docs/plans/product-search.md (4 milestones, 2 checkpoints)
**Top risk first:** M1 measures FTS ranking and index build time on a staging copy
**Questions for you:** (1) anonymous users see prices? (2) OK to add a GIN index on products in prod?
**Assumed:** English-only search; 200k products
**Next:** approve the plan, then I start M1About this skill
Written and maintained by the Claude Skills editors to the same editorial standard as every skill in the directory: a selective trigger, a real workflow, known pitfalls and a verification step. First published , last updated . MIT licensed.