planning-and-task-breakdown

name	planning-and-task-breakdown
description	Use when you have a spec or PRD that needs decomposing into small, verifiable implementation tasks. Use before any build cycle to ensure tasks are thin vertical slices with clear acceptance criteria.

Core Workflow

1. Read the spec — load the approved PRD — a GitHub issue with label idea. If no approved PRD exists, stop and tell the user to run /spec first.
2. Identify vertical slices — each slice cuts end-to-end (schema → API → UI → tests). Each must be shippable independently. Bad: "All the database schema". Good: "User can create a task".
3. Define acceptance criteria per slice — concrete and testable. "The create button is disabled when the form is invalid" not "validation works".
4. Order by dependency — which slices block others. Produce a DAG, not a linear list.
5. Assign priority — p1 (core path), p2 (important), p3 (nice to have).
6. Assign execution label — afk (agent can do this autonomously) or hitl (needs human judgement).
7. Present to user — ordered list with dependencies, AC, priority, execution label. Confirm before creating issues.

Slice Quality Checklist

A good slice:

• Cuts end-to-end (schema → API → UI → tests)
• Shippable independently — leaves nothing in a broken state
• Has concrete, testable acceptance criteria
• Can be implemented in a single PR (~100-300 lines)
• Has a clear "done" state with no ambiguity

Common Rationalizations

Rationalization	Reality
"Let's do all the schema changes first"	That's horizontal slicing. Schema without API or UI can't be shipped or verified.
"This task is too small to bother with AC"	If it's too small for AC, it's too small to track as a task. Merge it.
"I'll figure out the dependencies as I go"	Without dependency ordering, you will block yourself and produce merge conflicts.
"Everything is p1"	If everything is p1, nothing is. Force ranking.

Red Flags

• A slice doesn't produce user-visible value on its own
• Acceptance criteria are untestable ("works well", "fast")
• You have more hitl slices than afk — you're keeping too much for humans
• Slices are horizontal (all schema, all API, all UI)
• A slice is estimated at >400 lines of change

Verification

• Every acceptance criterion from the spec maps to at least one slice
• No slice depends on a slice that doesn't exist yet
• Each slice has exactly one execution label (afk or hitl)
• Priority labels are assigned and ranked
• User confirmed the breakdown

Issue Creation

When creating GitHub issues from a breakdown:

Labels: Feature vs Non-Feature

Feature slices (new user-facing capability) — apply hitl and needs-planning labels. Features require a proper planning session per slice before implementation. Do NOT apply afk, planned, or feature labels to feature issues.

Non-feature slices (bugs, chores, refactors, tech debt) — may use afk and planned labels directly.

Execution labels as metadata

• afk / hitl remain useful metadata in the plan itself (to signal autonomy vs human judgement), but for feature issues they are planning-stage classification only — not GitHub labels.
• Each feature slice must go through /plan Phase 2 (Detailed Planning) before implementation begins.

Detailed Planning

After issues are created with needs-planning, run detailed planning per-slice. This produces an implementation-ready issue body that /build can consume. The trigger is the needs-planning label — query with gh issue list --label needs-planning.

1. Fetch the issue — gh issue view <number>. Capture the current body as a baseline.
2. Explore the codebase — identify:
   • Relevant modules and existing patterns in the target area
   • Files the implementation will touch
   • Interfaces/public APIs it will call or extend
   • Existing tests it should follow the pattern of
3. Write the detailed plan into the issue body. Structure it as:
   • Problem statement — clear why
   • Acceptance criteria — specific, testable outcomes, one per line
   • Implementation notes — module design, seams, specific files, key interfaces
   • Test strategy — which layers (unit/integration/e2e), what to mock, edge cases
   • Out of scope — what this slice deliberately does NOT touch
   • Dependencies — other issues/PRs/features this depends on
4. Update the issue — gh issue edit <number> --body "<updated body>"
5. Transition labels — gh issue edit <number> --remove-label needs-planning --add-label planned
6. Re-evaluate execution — run the DoR checklist. If all criteria met → afk. Otherwise → hitl. The invariant from the triage command applies: planned MUST have exactly one of afk or hitl.

DoR Checklist (from triage.md)

#	Criterion
1	Problem statement — clear why
2	Acceptance criteria — specific, testable outcomes
3	Technical context — enough to know where to start
4	Testing strategy — which layers, mocks needed
5	Out of scope — what is NOT being done
6	Dependencies — other issues, PRs, external changes
7	No open questions — design forks resolved

Verification

• Every issue that was needs-planning is now planned
• Each planned issue has exactly one of afk or hitl
• Each issue body contains a detailed implementation plan a developer can build from
• The issue body passes the DoR checklist

Constraints

MUST DO

• Slice vertically — every slice must trace schema → API → UI → tests.
• Assign one execution label per slice (afk or hitl) as planning metadata, not as a GitHub label for features.
• Verify every spec acceptance criterion is covered by at least one slice.
• Get user approval on the breakdown before creating issues.
• For features: each slice requires its own planning session before implementation starts.

MUST NOT DO

• Create horizontal slices (schema-only, API-only, etc.).
• Bundle multiple concerns into one slice.
• Assign hitl when the work can be done AFK — resist the urge to gate on humans.
• Proceed to implementation before the plan is approved.
• Apply afk, planned, or feature labels to feature issues — features use hitl and needs-planning instead.
• PRD parent issues get a prd label in addition to hitl and needs-planning.