paulund/planning-and-task-breakdown

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.