/planning-and-task-breakdown

name: planning-and-task-breakdown
type: workflow
description: "When dealing with a complex issue, epic, or multi-step feature request, break it down into executable, testable, agent-ready tasks before writing code."
argument-hint: "[epic-description-or-issue-url]"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
effort: 3
agent: lead-programmer
when_to_use: "When starting a complex project, receiving an epic or vague large-scale request, turning an approved spec into implementation tasks, or when the user invokes /plan."

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