planning-and-task-breakdown

Planning and Task Breakdown

Purpose

Turn approved requirements into an implementation plan that another agent can execute task by task without guessing. The plan must lock down scope, file ownership, dependencies, test strategy, and verification before any code changes.

This is a Plan Gate under using-sdd. A plan is not permission to execute. The user must approve the plan before RED tests, production edits, or implementation subagents begin.

Prefer tracer-bullet vertical slices: each task should deliver the thinnest complete path that is independently verifiable. Avoid horizontal tasks that only build one layer unless that layer is a prerequisite contract, migration, or bounded infrastructure step with its own verification.

When the plan will later be published to an issue tracker, keep each task shaped like an independently grabbable issue: narrow outcome, explicit blockers, acceptance criteria, and enough context that another agent or human can execute it without reopening the whole spec.

Workflow

1. Establish Inputs

• Identify the source of truth: user request, spec file, issue, PRD, bug report,

or prior conversation summary.

• Read only the files needed to understand scope, architecture boundaries, and

existing patterns.

• Identify the applicable pre-code gate from using-sdd.
• If requirements are vague, stop and route to deep-interview or

spec-driven-development before planning.

2. Scope Check

Before tasking, decide whether this is one plan or multiple plans.

Split into separate plans when the request contains independent subsystems, such as billing plus analytics plus auth, or mobile plus backend plus release automation. Each plan must produce working, testable value on its own.

If the request is too broad for one plan, present the split and ask which plan to write first.

3. File Responsibility Map

Before defining tasks, map the files or modules that will be created or modified.

For each file, capture:

• Purpose
• Owner task
• Whether it is created, modified, or tested
• Verification command/check that exercises it

Prefer small files with clear responsibilities. Follow existing codebase patterns. Do not add unrelated refactors. If an existing file is too large and the requested change touches its tangled area, include a scoped split task and explain why it is necessary.

4. Task Decomposition

Break work into atomic tasks. Each task should be small enough to execute and verify independently.

A valid task:

• Touches one logical behavior or one infrastructure step
• Delivers a tracer-bullet vertical slice when user-facing behavior crosses

multiple layers

• Lists exact files, or a bounded discovery step if the exact file is unknown
• Includes TDD RED/GREEN/REFACTOR steps for behavior changes
• Includes exact commands and expected outcomes
• Has clear acceptance criteria
• Can be reviewed independently
• Is marked AFK when an agent can execute it without more human judgment, or

HITL when it requires human approval, design choice, external access, manual review, or unresolved tradeoff

Invalid tasks:

• "Build the backend"
• "Add validation and error handling"
• "Write tests for the above"
• "Implement similar logic"
• Any task spanning DB, API, UI, docs, and deployment at once
• Any horizontal slice that cannot be demonstrated or verified without a later

task, unless it is explicitly a contract or setup task

4a. AFK/HITL Classification

Classify each task before presenting the plan:

| Classification | Meaning | Typical examples | | --- | --- | --- | | AFK | Agent-ready. Requirements, files, acceptance criteria, and verification are clear enough to execute without more human decisions. | Narrow bug fix, approved behavior slice, mechanical docs update, isolated test coverage | | HITL | Human-in-the-loop. Work is blocked on judgment, access, design approval, or a durable tradeoff. | Architecture choice, UX decision, credentials, release approval, ADR acceptance |

Default to HITL when the task contains unresolved product, security, release, or architecture judgment. Do not hide uncertainty inside an AFK task.

Also classify the plan's execution risk honestly:

• AFK tasks should already have settled scope, files, verification, and no

pending design choice hidden behind "implement as needed".

• HITL tasks should say exactly what human input is missing: approve copy,

pick schema path, provide credential, accept ADR, confirm rollout window.

• If a task becomes AFK only after one upstream HITL decision, keep that

dependency explicit instead of pretending the whole chain is agent-ready.

4b. Tracer-Bullet Issue Shape

When a task represents user-facing behavior or a reviewable slice, shape it like an issue another implementer could pick up directly:

• Title: short outcome, not implementation mechanism
• Classification: AFK or HITL
• Blocked by: exact upstream task(s) or None
• What changes end-to-end: the thinnest complete path across relevant layers
• Acceptance criteria: demoable or independently verifiable checks

Do not produce pseudo-issues such as "backend support", "frontend wiring", or "add tests" unless they are genuine prerequisite setup tasks with their own verification contract.

5. Dependency Mapping

Order tasks by dependency:

1. Contracts and interfaces before consumers
2. Schema/data changes before API code
3. API behavior before UI integration
4. Implementation before docs
5. Tests and verification at every task boundary

Mark tasks as sequential unless they touch disjoint files and have no input dependency. If parallel execution is genuinely safe, say whether to use fork-join or orchestrate.

Prefer blocker-first sequencing that mirrors issue-tracker publication order: publish or present true blockers before dependent slices so later tasks can reference real upstream work instead of vague "depends on prior implementation".

6. Create Plan and Request Approval

Output the plan in the required format below. End by asking for explicit approval to execute Task 1. Do not create tests, edit production files, or spawn implementation agents before approval.

Required Plan Format

Use this structure exactly. Keep it concise, but do not omit required fields.

# [Feature/Epic Name] Implementation Plan

**Goal:** [One sentence describing the working outcome]
**Source of Truth:** [spec/issue/request path or short description]
**Pre-Code Gate:** Plan Gate required because [multi-step / multi-file / cross-domain reason]
**Approval Required Before:** RED tests, production edits, implementation subagents
**Execution Mode Recommendation:** [Inline TDD | subagent-driven-development | orchestrate | fork-join] because [reason]
**Slice Strategy:** [Tracer-bullet vertical slices | Contract/setup tasks first, then vertical slices] because [reason]

## Architecture Summary

[2-4 sentences describing approach, boundaries, data/control flow, and how this
fits existing patterns.]

## File Responsibility Map

| File | Action | Responsibility | Owner Task | Verification |
| --- | --- | --- | --- | --- |
| `exact/path/file.ext` | Create/Modify/Test | [purpose] | Task N | `[command/check]` |

## Plan

### Task 1: [Atomic Outcome]

**Issue Shape:** [Short issue-style title]
**Classification:** [AFK | HITL] because [why the agent can proceed alone or what human decision is required]
**Purpose:** [Why this task exists]
**Dependencies:** None / Task N
**Files:**
- Create: `exact/path/new-file.ext`
- Modify: `exact/path/existing-file.ext`
- Test: `exact/path/test-file.ext`

**Acceptance Criteria:**
- [ ] [Concrete observable result]
- [ ] [Edge case or failure behavior]
- [ ] [Independent verification/demo result for this slice]

- [ ] **Step 1: RED - write the failing test**

Describe the exact test to add. Include code when the API or assertion is known:

it("does the expected behavior", () => { // concrete