--- name: planning-and-task-breakdown description: Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, when parallel work is possible, or when the user wants to grill a plan before implementation. --- # Planning and Task Breakdown ## Overview Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session. ## 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 - The user asks to grill or stress-test a draft plan before implementation **When NOT to use:** Single-file changes with obvious scope, or when the spec already contains well-defined tasks. ## Output Location By default, save the plan to `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`: - `{area}` — the functional area; match the area of the PRD this plan implements. - `{prd-name}` — the name of the PRD this plan implements (e.g. `PRD3-tournament-copy`). If there is no PRD, use a short kebab-case topic slug instead. - `{phase}` — include a phase suffix **only** when the plan is deliberately split across more than one plan file. For a single-file plan, drop it (`PLAN-{prd-name}.md`). The task list is **embedded** in the plan file as the `## Task List` section. Do **not** create a separate `todo.md`. Match the project's existing `docs` vs `Docs` capitalization, and create the directory if it does not exist. **Project overrides:** if `.ai/agent-fleet-overrides.md` has a `## planning-and-task-breakdown` section, its keys (`plan-dir`, `naming`, `todo`) override these defaults — `todo: separate` restores a standalone `todo.md`. See [docs/agent-fleet-setup.md](../../docs/agent-fleet-setup.md). ## 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 - Map dependencies between components - Note risks and unknowns **Do NOT write code during planning.** The output is a plan document, not implementation. **Grilling mode:** If the user asks to grill/stress-test the plan, or Step 1 reveals a load-bearing assumption, read the shared internal helper at [`../_internal/grilling.md`](../_internal/grilling.md) before writing tasks. Resolve decisions one at a time; update Architecture Decisions, Risks, and Open Questions with accepted, rejected, or deferred choices. ### 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 Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time: **Bad (horizontal slicing):** ``` Task 1: Build entire database schema Task 2: Build all API endpoints Task 3: Build all UI components Task 4: Connect everything ``` **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 vertical slice delivers working, testable functionality. ### Step 4: Write Tasks Each task follows this structure: ```markdown ## Task [N]: [Short descriptive title] **Description:** One paragraph explaining what this task accomplishes. **Acceptance criteria:** - [ ] [Specific, testable condition] - [ ] [Specific, testable condition] **Verification:** - [ ] Tests pass: `npm test -- --grep "feature-name"` - [ ] Build succeeds: `npm run build` - [ ] Manual check: [description of what to verify] **Dependencies:** [Task numbers this depends on, or "None"] **Files likely touched:** - `src/path/to/file.ts` - `tests/path/to/test.ts` ``` ### 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. Verification checkpoints occur after every 2-3 tasks 4. High-risk tasks are early (fail fast) Add explicit checkpoints: ```markdown ## Checkpoint: After Tasks 1-3 - [ ] All tests pass - [ ] Application builds without errors - [ ] Core user flow works end-to-end - [ ] Review with human before proceeding ``` ## Task Sizing Guidelines If a task is 5-8 files (Multi-component feature , such as Search with filtering and pagination) or larger, it should be broken into smaller tasks. An agent performs best on 1-5 file tasks. **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 ```markdown # Implementation Plan: [Feature/Project Name] ## Overview [One paragraph summary of what we're building] ## Architecture Decisions - [Key decision 1 and rationale] - [Key decision 2 and rationale] ## Task List ### Phase 1: Foundation - [ ] Task 1: ... - [ ] Task 2: ... ### Checkpoint: Foundation - [ ] Tests pass, builds clean ### Phase 2: Core Features - [ ] Task 3: ... - [ ] Task 4: ... ### Checkpoint: Core Features - [ ] End-to-end flow works ### Phase 3: Polish - [ ] Task 5: ... - [ ] Task 6: ... ### Checkpoint: Complete - [ ] All acceptance criteria met - [ ] Ready for review ## 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) ## Common Rationalizations | Rationalization | Reality | |---|---| | "I'll figure it out as I go" | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours. | | "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. | | "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. | | "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. | ## Red Flags - Starting implementation without a written task list - Tasks that say "implement the feature" without acceptance criteria - No verification steps in the plan - All tasks touches more than 8+ files - No checkpoints between tasks - Dependency order isn't considered ## Verification Before starting implementation, confirm: - [ ] Every task has acceptance criteria - [ ] Every task has a verification step - [ ] Task dependencies are identified and ordered correctly - [ ] No task touches more than ~5 files - [ ] Checkpoints exist between major phases - [ ] The human has reviewed and approved the plan - [ ] If grilling was invoked, each load-bearing decision has an accepted/rejected/deferred status in the plan - [ ] No open questions left (All are resolved/answered/commented) ## See Also Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See `references/definition-of-done.md`.