Break Down Specs into Testable, Ordered Implementation Tasks

Decomposes work into small, verifiable tasks with explicit acceptance criteria, on the premise that good task breakdown is what separates an agent that completes work reliably from one that produces a tangled mess; every task should be small enough to implement, test and verify in a single focused session.

The process runs in five steps. Step 1 enters a read-only plan mode before writing any code, reading the spec and relevant codebase sections, identifying existing patterns and conventions, mapping dependencies between components, and noting risks and unknowns, with the output being a plan document, not implementation. Step 2 identifies the dependency graph, mapping what depends on what (for example database schema feeding API models and seed data, API models feeding endpoints and validation logic, endpoints feeding a frontend API client, which feeds UI components), with implementation order following that graph bottom-up so foundations get built first. Step 3 slices vertically rather than horizontally: instead of building the entire database, then the entire API, then the entire UI, it builds one complete feature path at a time (for example, one task for account creation covering its schema, API and UI together, rather than one task per layer across all features), since each vertical slice delivers working, testable functionality.

Step 4 writes each task to a fixed structure: a short descriptive title, a one-paragraph description of what the task accomplishes, specific and testable acceptance criteria as checkboxes, a verification section (tests passing, the build succeeding, and any manual check needed), the task numbers it depends on or "None", the files likely touched, and an estimated scope (Small: 1-2 files, Medium: 3-5 files, Large: 5+ files). Step 5 orders tasks and adds checkpoints so dependencies are satisfied first, each task leaves the system in a working state, verification checkpoints occur after every 2-3 tasks, and high-risk tasks come early to fail fast, with each checkpoint explicitly checking that all tests pass, the application builds without errors, the core user flow works end-to-end, and a human has reviewed before proceeding.

A fixed task-sizing scale runs from XS (a single file, a single function or config change, like adding a validation rule) through S (1-2 files, one component or endpoint), M (3-5 files, one feature slice like a registration flow), L (5-8 files, a multi-component feature like search with filtering and pagination), to XL (8+ files, too large and must be broken down further); an agent performs best on S and M tasks, and any L-or-larger task should be split. Signals that a task needs further breakdown: it would take more than one focused session (roughly 2+ hours of agent work), its acceptance criteria can't be described in 3 or fewer bullet points, it touches two or more independent subsystems (such as auth and billing), or the task title contains the word "and" (a sign it is actually two tasks).

A full plan document follows a fixed template: an overview paragraph, a list of key architecture decisions with rationale, a phased task list (each phase's tasks followed by its own checkpoint, for example Foundation, Core Features, then Polish, ending in a final checkpoint confirming all acceptance criteria are met and the work is ready for review), a risks-and-mitigations table (risk, impact, mitigation strategy), and an open-questions section for anything needing human input.

When multiple agents or sessions are available, parallelization opportunities are sorted into three tiers: safe to parallelize (independent feature slices, tests for already-implemented features, documentation), must be sequential (database migrations, shared state changes, dependency chains), and needs coordination (features sharing an API contract, where the contract should be defined first and then parallelized).

It names and counters four common rationalizations: "I'll figure it out as I go" leads to a tangled mess and rework, since ten minutes of planning saves hours; "the tasks are obvious" still deserves writing down, since explicit tasks surface hidden dependencies and forgotten edge cases; "planning is overhead" is wrong because planning is the task, implementation without a plan is just typing; and "I can hold it all in my head" ignores that context windows are finite while written plans survive session boundaries and compaction. Six red flags mark a plan gone wrong: starting implementation without a written task list, tasks that say "implement the feature" with no acceptance criteria, no verification steps in the plan, every task sized XL, no checkpoints between tasks, and dependency order not considered.

Before implementation starts, a verification checklist confirms every task has acceptance criteria, every task has a verification step, task dependencies are identified and correctly ordered, no task touches more than roughly 5 files, checkpoints exist between major phases, and a human has reviewed and approved the plan. Per-task acceptance criteria answer "did we build the right thing" and sit on top of the project-wide Definition of Done, documented separately in references/definition-of-done.md, the standing bar every task clears before it counts as done.

Use it when a spec needs breaking into implementable units, a task feels too large or vague to start, work needs parallelizing across multiple agents or sessions, scope needs communicating to a human, or the implementation order isn't obvious. Skip it for single-file changes with obvious scope, or when the spec already contains well-defined tasks.

Input is a spec or feature request plus the relevant codebase. Output is a phased implementation plan document with vertically-sliced, sized tasks, each carrying acceptance criteria, verification steps, dependencies and files touched, plus checkpoints between phases and a risks-and-mitigations table.

References a separate project-wide references/definition-of-done.md that sits above its own per-task acceptance criteria.

Anyone breaking a spec or feature into implementable units for an agent or a team, especially when work needs to be parallelized, sized, or communicated to a human reviewer before implementation starts.