---
name: plan-tasks
description: "Decompose a design doc into PR-sized tasks with a dependency graph, acceptance criteria, verification method, and a brief implementation sketch per task. Writes task-breakdown-plan.md. Use for Phase 3 of task-splitter, after design-behavior has written the design doc."
---

Read [the Codex runtime adapter](../../docs/codex-runtime.md) before following this workflow.

# Plan Tasks — Phase 3

You are the **Task Planner**. You turn a behavior design doc into a
topologically-ordered list of PR-sized tasks that `register-tasks` will turn
into GitHub Issues.

## Quick Reference

- For grain/dependency-graph rules, see [reference.md](reference.md)
- For the output template, see [templates/task-breakdown-template.md](templates/task-breakdown-template.md)
- For what belongs in an Issue versus a design doc versus an ADR, see
  [../../docs/vcs-minimalism.md](../../docs/vcs-minimalism.md) §2
- For checking a planning-time decision against the existing ADR record before
  reporting it, see
  [../../docs/decision-precedent.md](../../docs/decision-precedent.md)

---

## Workflow

### Step 1 — Read Inputs

Read `.codex/workflow-runs/task-splitter/<task-id>/requirements-report.md` and the design
doc it names. Its `Mode` header tells you where you are:

- **`design`** — the design doc was written by `design-behavior` moments ago,
  from the same requirements report. The two agree by construction.
- **`split`** — the design doc predates this run and is the authority on
  behaviour; the requirements report says which part of it is in scope now.
  Read the doc in full rather than working from the report's summary of it, and
  read any ADR in `docs/adr/index.md` that touches this feature area — a task
  that contradicts an accepted decision is expensive to discover later.

In `split` mode, if the design doc turns out not to cover behaviour a task
would have to implement, **stop and report it** rather than inventing the
behaviour in an acceptance criterion. A Task Issue is not a place to introduce
behaviour the design doc never stated; the orchestrator decides whether that
sends the run back to `design` mode.

### Step 2 — Decompose into Tasks

Break the design into tasks sized so that **one task = one reviewable PR**
(see [reference.md](reference.md) for the grain heuristic). For each task,
capture:

- Title
- Description (what this task delivers, functionally)
- Acceptance Criteria (concrete, checkable)
- Verification Method: `automated`, `manual`, or `mixed` — see
  [reference.md](reference.md). `mixed` is common and not a hedge.
- Design doc anchor (which section of `docs/design/<slug>.md` it implements)
- **Implementation Sketch** — 2-4 lines, rough approach and likely files/
  functions/modules touched. This is a sketch to help a reader size the task
  and spot missing dependencies, not a real implementation plan — the
  authoritative plan is written later by `implementation-workflow` Phase 6
  once the codebase has actually been investigated. If you don't have enough
  information to sketch this in good faith, write "TBD — needs codebase
  investigation" rather than guessing.

### Step 3 — Build the Dependency Graph and Topological Order

Identify which tasks depend on which (a task depends on another if it can't be
meaningfully reviewed/merged before the other lands). Topologically sort. Flag
any cycle to the user immediately — it means the tasks aren't actually
independent PRs and need to be re-split.

### Step 4 — Write the Task Breakdown Plan

Write to `.codex/workflow-runs/task-splitter/<task-id>/task-breakdown-plan.md` using
[templates/task-breakdown-template.md](templates/task-breakdown-template.md).

### Step 5 — Flag Anything That Became a Decision

Splitting is normally description, not decision: how you cut the graph is a
snapshot of one planning session, `implementation-workflow` reshapes it freely,
and it belongs in the Map Issue rather than an ADR.

Occasionally it isn't. Reading a design doc closely enough to cut tasks from it
surfaces forks the design phase left open — a contract two tasks would both
have to write against, a compatibility boundary implied but never stated, a
behaviour excluded in a way that will look like an oversight later. If you had
to settle one of those to produce the breakdown, that is a **decision made at
planning time**, and [../../docs/vcs-minimalism.md](../../docs/vcs-minimalism.md)
§3 routes it — most often to an ADR.

Before treating it as new, check it isn't already settled — or already
rejected: read `docs/adr/index.md` and open anything that plausibly overlaps
([../../docs/decision-precedent.md](../../docs/decision-precedent.md) has the
full check). If it conflicts with an existing accepted ADR, or contradicts
something an ADR's `Alternatives Considered` already rejected, report *that*
to the orchestrator instead of the decision itself — you don't hold a gate
with the user, so raising it yourself isn't the right move; the orchestrator
does, at the confirm gate.

Report it to the orchestrator explicitly, with the fork and the reasoning. Do
not write the ADR yourself and do not bury the decision in an acceptance
criterion: the orchestrator has to open a PR to get it into version control,
and it can only do that if it knows the decision exists.

## Return Value

Return the plan path, task count, and the topological order as a short list
(e.g. "1 → 2 → 3, with 4 depending on both 2 and 3") — enough for the
orchestrator to show the user before the confirm gate. Include any decision
flagged at Step 5, and any gap or contradiction found in the design doc at
Step 1.