Planning and task breakdown

Planning and Task Breakdown

Decompose work into small, verifiable tasks with a parallel-dispatchable structure. The output is a plan document — never code — that downstream runners (CI matrices, single-agent execution sessions) consume to do the work.

When to use

• After a /shape brief covering multi-repo, multi-week, or multi-slice work
• When a spec or task feels too large to start in one session
• When work needs to parallelize across agents or sessions
• When implementation order isn't obvious

When not to use. Single-file changes with obvious scope, or specs that already contain well-defined tasks.

The planning process

1. Plan mode. Read in read-only mode. Map dependencies, note risks. Do not write code during planning.
2. Identify the dependency graph. Bottom-up — foundations first.
3. Slice vertically. Each task is a feature path through every layer it needs (schema + API + UI), not a horizontal layer of the system. Horizontal slicing produces half-finished branches.
4. Write task blocks. Each task is YAML frontmatter (id, depends_on, parallel_safe, conflicts_with, files_write, files_read, branch_suffix, scope) plus prose (description, acceptance, verification). Format and field semantics: references/task-block-format.md.
5. Order and checkpoint. Phases are presentational; the DAG is the execution order. Checkpoints are synchronization barriers — dispatch pauses until they clear.
6. Declare the Execution DAG. Top-of-document summary of edges using → and ||. Format and dispatcher contract: references/execution-dag.md.

Universal rules

• Stable IDs, never renumbered. Use content-based slugs (T-auth-schema). Renumbering breaks every reference. Retire dropped IDs rather than reusing them.
• files_write is authoritative, not advisory. The dispatcher uses it for conflict detection. Under-declare → parallel collisions; over-declare → false serialization.
• The DAG is a summary, not the source of truth. Per-task depends_on is authoritative. The verification checklist enforces that they agree.
• Day-zero ready set must be non-empty. At least one task has depends_on: []. If none do, the plan is malformed.
• scope: L must be split before dispatch. Agents perform best on XS / S / M.
• Plan, do not implement. This skill never writes code. The output is a plan document; execution is a separate step.
• Every plan carries a **Status:** line. Lifecycle proposed → in-progress → shipped | superseded. A fresh plan starts at proposed; keep it current as the work moves. It is the signal for retiring completed plans (prune shipped/superseded plans manually), so an unmarked plan never gets recognized as done. See assets/plan-document-template.md.

References

• references/task-block-format.md — per-task YAML frontmatter and prose structure, field-by-field semantics
• references/execution-dag.md — DAG syntax, dispatcher contract, checkpoints, worked example
• assets/plan-document-template.md — full document template
• references/parallelization-decisions.md — when to set each YAML field; contract-first, barrel-file, migration patterns
• references/task-sizing-and-redflags.md — sizing table, when to split, common rationalizations, red flags

Verification

Before starting implementation, confirm:

• The plan has a **Status:** line (a fresh plan starts at proposed)
• Every task has a stable id (content-based slug, not a number)
• Every task has acceptance criteria and a verification step
• Every task declares depends_on, parallel_safe, files_write
• Every pair of tasks whose files_write overlap is in each other's conflicts_with
• At least one task has depends_on: [] (a non-empty day-zero ready set)
• No task is scope: L (split it before dispatch)
• No task touches more than ~5 files
• The Execution DAG matches the per-task depends_on (no orphan IDs, no missing edges)
• Checkpoints exist between major phases and are referenced in the DAG
• The human has reviewed and approved the plan