planning-and-task-breakdown

name	planning-and-task-breakdown
description	Use when an accepted specification or plan must become ordered tasks, vertical slices, atomic commits, or parallel work boundaries.

Planning and Task Breakdown

Write the plan and its handoff with lifecycle-documentation.

When to Use

• You have a spec and need to break it into implementable units
• A task feels too large or vague to start
• Work needs to be parallelized across multiple agents or sessions
• You need to communicate scope to a human
• The implementation order isn't obvious

When NOT to use: Single-file changes with obvious scope, or when the spec already contains well-defined tasks.

Planning hierarchy

Plan
└── Milestone: a checkpoint outcome
    └── Task: an implementable vertical slice with acceptance criteria
        └── Commit: an atomic, revertable logical change

A milestone contains one or more ordered tasks. A task contains one or more ordered commits. Planning names affected areas and required verification outcomes; design adds exact future file paths, signatures, and commands.

The Planning Process

Step 1: Enter Plan Mode

Before writing any code, operate in read-only mode:

• Read the spec and relevant codebase sections
• Identify existing patterns and conventions, citing the exact path:line evidence
• Find the closest implemented analogue and state what is reusable and what differs
• Map dependencies between components
• Note risks and unknowns

Record the searches used when no relevant prior art exists. Never use “the codebase does X” or “follow the existing pattern” without a concrete citation.

Do NOT write code during planning. The output is a plan document, not implementation.

Step 2: Identify the Dependency Graph

Map what depends on what:

Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations

Implementation order follows the dependency graph bottom-up: build foundations first.

Step 3: Slice Vertically

Break work into vertical slices — one complete feature path through every layer at a time, not all-DB-then-all-API-then-all-UI. See the incremental-implementation skill for the full treatment (contract-first and risk-first variants included).

Good (vertical slicing):

Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a task (task schema + API + UI for creation)
Task 4: User can view task list (query + API + UI for list view)

Each slice delivers working, testable functionality and becomes a task below. A task may require more than one atomic commit to reach its acceptance criteria.

Step 4: Write Tasks

Each task follows this structure:

## Task [N]: [Short descriptive title]

**Description:** One paragraph explaining what this task accomplishes.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification:**
- [ ] Required outcome: [behavior, quality gate, or observation that proves the task]
- [ ] Evidence needed: [test result / type or build result / rendered or runtime observation]

**Dependencies:** [Task numbers this depends on, or "None"]

**Affected areas:**
- [Subsystem, boundary, or component; design supplies exact future files]

**Evidence and prior art:**
- `src/existing-flow.ts:24-61` — analogous control flow; reuse its boundary, not its persistence model
- Search with no result: `rg "alternate-flow" src tests`

**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]

**Commits:**
1. `[atomic logical change]`
2. `[next atomic logical change, when needed]`

Step 5: Order and Checkpoint

Arrange tasks so that:

1. Dependencies are satisfied (build foundation first)
2. Each task leaves the system in a working state
3. A verification checkpoint closes every milestone
4. High-risk tasks are early (fail fast)

Add explicit checkpoints:

## Checkpoint: [Milestone outcome]
- [ ] All tests pass
- [ ] Application builds without errors
- [ ] Core user flow exercised end-to-end — the command that drives it passes, or drive it manually and screenshot the result
- [ ] Human sign-off: a person other than the agent has reviewed and approved proceeding (the agent cannot tick this itself)

Task Sizing Guidelines

Size	Files	Scope	Example
XS	1	Single function or config change	Add a validation rule
S	1-2	One component or endpoint	Add a new API endpoint
M	3-5	One feature slice	User registration flow
L	5-8	Multi-component feature	Search with filtering and pagination

The table sizes tasks. One commit is one revertable logical change (~100 lines — see git-workflow-and-versioning). A task contains however many atomic commits it needs to satisfy its acceptance criteria; if one commit grows too broad, split it without inventing another task unless the acceptance boundary also changes.

When to break a task down further:

• It would take more than one focused session (roughly 2+ hours of agent work)
• You cannot describe the acceptance criteria in 3 or fewer bullet points
• It touches two or more independent subsystems (e.g., auth and billing)
• You find yourself writing "and" in the task title (a sign it is two tasks)

Plan Document Template

# Implementation Plan: [Feature/Project Name]

## Overview
[One paragraph summary of what we're building]

## Architecture Decisions
- [Key decision 1, rationale, and exact `path:line` evidence]
- [Key decision 2, rationale, and exact `path:line` evidence]

## Prior Art and Evidence
| Claim / decision | Evidence | Interpretation and limits | Confidence |
| --- | --- | --- | --- |
| [...] | `path/to/file.ts:10-28` or primary-source URL | [...] | High / Medium / Low |

## Task List

### Milestone 1: Foundation
- [ ] Task 1: ...
  - Commit 1: ...
  - Commit 2: ...

### Checkpoint: Foundation
- [ ] Tests pass, builds clean

### Milestone 2: Core Features
- [ ] Task 2: ...
  - Commit 3: ...
- [ ] Task 3: ...
  - Commit 4: ...

### Checkpoint: Core Features
- [ ] End-to-end flow exercised — the command that drives it passes (or drive it and screenshot)

### Milestone 3: Polish
- [ ] Task 4: ...
  - Commit 5: ...
  - Commit 6: ...

### Checkpoint: Complete
- [ ] Each acceptance criterion checked against its verification command or observation
- [ ] Human sign-off obtained before review (external approval — the agent cannot tick this itself)

## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | [High/Med/Low] | [Strategy] |

## Open Questions
- [Question needing human input]

Parallelization Opportunities

When multiple agents or sessions are available:

• Safe to parallelize: Independent feature slices, tests for already-implemented features, documentation
• Must be sequential: Database migrations, shared state changes, dependency chains
• Needs coordination: Features that share an API contract (define the contract first, then parallelize)

Verification

Before starting implementation, confirm:

• Every task has acceptance criteria
• Every task names its verification outcome and required evidence
• Every task contains one or more ordered atomic commits
• Every material claim about the repository cites exact lines of code or tests
• Each major decision names concrete prior art or records the search that found none
• Observations, inferences, and recommendations are distinguishable
• Task dependencies are identified and ordered correctly
• Checkpoints exist between milestones
• A human other than the agent has reviewed and approved the plan (external sign-off — the agent cannot tick this itself)