Playbook: Large Tasks

Objective

Deliver a body of work that does not fit one trustworthy Claude Code session — by splitting into sequenced, verifiable slices with durable handoffs — without losing architectural coherence or accumulating half-wrong context.

When to use

Estimates exceed ~one focused session; the plan has >~8 steps; multiple packages/domains; or prior attempts ended in stuck loops. For a single bounded feature, prefer Add a Feature. For greenfield product arcs, MVP Build already encodes slicing.

Inputs required

• A written goal and non-goals (spec or ADR-backed).
• Inventory of subsystems touched.
• Definition of "slice done" (gates + human check).
• Branch strategy (stacked PRs vs long-lived branch with frequent merges from main).

Step-by-step process

1. Decompose before any implementation session

Given goal <goal> and constraints <list>, propose a decomposition.

Rules:
- Each slice is verifiable end-to-end or with a clear intermediate proof
- Each slice fits one session (roughly: ≤~10 files or one subsystem seam)
- Dependencies between slices are explicit (DAG)
- Identify the riskiest slice and whether it should go first
- Flag decisions that are human-owned before slice 1

Do not write code. Output a numbered slice list with: goal, allowlist hint,
verification, and prerequisites.

You edit the DAG. Agents often propose horizontal layers ("do all DB first") — invert toward vertical or seam-based slices that prove something.

2. Write slice contracts into the repo

Durable > chat. Example:

## Slice 3 — Extract proration pure function
- Spec: specs/012-billing-proration.md §Algorithm
- Allowlist: src/domain/billing/proration.ts, *.test.ts
- Prerequisites: Slice 2 merged
- Verification: `npm test -- proration` + examples from spec
- Out of scope: HTTP, Stripe, migrations
- Handoff: update specs/012/STATUS.md

Keep status in-repo (specs/.../STATUS.md or PLAN.md) so a fresh session doesn't need the old transcript. See Docs as Memory.

3. One slice per session — fresh context

Read CLAUDE.md, specs/<id>.md, and specs/<id>/STATUS.md.
Implement ONLY slice <n> as contracted.

Questions-first if the contract is ambiguous — stop and ask.
Plan mode if the slice touches >3 files.
When done: evidence (commands + output), update STATUS.md handoff section,
list discovered follow-ups without implementing them.

Do not continue to slice N+1 in the same session after a messy N. Context pollution is the failure mode this playbook exists to prevent.

4. Handoff note (minimum template)

## Handoff — slice <n>
- Done: <bullets>
- Not done / out of scope discoveries: <bullets>
- Files touched: <paths>
- Verify with: <commands you ran + results summary>
- Open questions: <for human>
- Next slice: <n+1> prerequisites satisfied? yes/no

5. Integration checkpoints

Every K slices (or before any user-visible release):

Checkpoint	Action
Merge from main	Resolve conflicts deliberately — don't let the agent "make it compile" across domains unsupervised
Full make check	Not only the slice's targeted test
Spec sync	Keeping Specs Alive
Architecture skim	No parallel modules; map still true — Navigability
Demo path	Human exercises the thickest vertical path so far

6. Parallelism (optional, constrained)

Parallel slices only if allowlists cannot overlap and contracts don't share undecided decisions. Otherwise serialize. See Coordination. Prefer one human integrating over three agents racing.

Human review points

1. Decomposition DAG — yours.
2. Riskiest-slice ordering — yours.
3. Each slice acceptance — human verify before N+1.
4. Integration checkpoints — you run the thick path.
5. Stop/kill criteria — if two slices in a row need Recovery, pause and replan the remaining DAG.

Expected artifacts

Slice list in-repo · STATUS/handoffs · stacked or sequential PRs · green gates per slice · integration notes · updated specs/ADRs for decisions made along the way.

Common failures

Symptom	Root cause	Early detection	Fix
Mega-session "almost done" for days	Refused to slice	Context thrash; contradictory edits	Hard reset; write DAG; one slice/session
Slices green, whole system wrong	Horizontal slicing	No vertical proof	Reorder; add integration checkpoint
Handoff only in chat	Next session re-derives wrong	STATUS.md missing	Require STATUS update in slice DoD
Parallel agents conflict	Overlapping allowlists	Merge hell	Serialize; shrink allowlists
Late architecture change invalidates early slices	Deferred human decision	Decision appears mid-epic	Pull What Not to Delegate decisions to the front; ADR

Recovery strategy

Thrashing on slice N: context reset, shrink allowlist, or split N into N.a/N.b. If the DAG was wrong: freeze implementation, rewrite remaining contracts, obsolete STATUS entries explicitly. Catastrophic branch: Recovery, then resume from last verified slice tag.

Acceptance criteria

• [ ] Work split into session-sized slices with a DAG
• [ ] Each merged slice has verification evidence and STATUS handoff
• [ ] No slice N+1 started on a failed or unverified N
• [ ] Integration checkpoints run on the real thick path
• [ ] Human-owned decisions resolved before slices that depend on them
• [ ] Final behavior matches the governing spec/ADR set

Related

• Add a Feature — single-feature loop this scales up.
• MVP Build — product-level slicing.
• Stuck Loops and Thrash — why fresh sessions matter.
• Scope and Context Failures — context overflow patterns.
• Multi-Agent Coordination — if you parallelize.
• Recovery — when a slice goes bad.