Sizing WUs

Right-sizing WUs is critical for flow. The most common sizing mistake is not oversized WUs — it is fragmenting one coherent outcome into many small WUs that cannot ship alone.

The Cohesion Rule (read this first)

Default bias: one coherent outcome = one WU.

Keep one WU when all are true:

• The acceptance criteria describe one coherent outcome.
• The work should land together to be meaningful.
• A single agent or handoff chain can finish it (see strategies below).
• The touched files support the same change, even across several files.

Do not split because work has multiple implementation steps, tests plus docs, more than one session, or several same-lane files.

Caution

Required question before splitting: can these parts ship, review, and roll back independently? If no, keep one WU and choose a better execution strategy instead.

Consolidation Checklist

Before proposing more than two WUs, run this checklist iteratively over every pair until no merge passes:

1. Same lane and same outcome? Merge.
2. Same file or module? Usually merge.
3. Either WU meaningless alone? Merge.
4. Split by phase rather than outcome? Merge.
5. Split by artifact type (tests/code/docs)? Merge.
6. Would a reviewer see one PR? Merge.

Run the checklist before presenting a WU list — a reviewer should never need to send a plan back for consolidation.

Complexity Assessment

Estimate WU “weight” using these heuristics. estimated_files counts artifacts the WU will modify, not files read for review. estimated_tool_calls covers the whole WU across handoffs. The 50-call current-session checkpoint trigger remains an independent safety rule.

Strategy tier	File ceiling	Tool-call ceiling	Context Budget	Strategy (sizing_estimate.strategy)
Simple	≤20	≤50	<30%	single-session
Medium	≤50	≤100	30-50%	checkpoint-resume
Complex	≤100	≤200	>50%	orchestrator-worker
Oversized	>100	>200	—	Re-estimate and re-check cohesion; do not invent a split

Tip

Thresholds select an execution strategy — they are not permission to split cohesive work. A Complex-but-atomic WU wants orchestrator-worker (one WU, coordinated workers), not decomposition. Work that outgrows one session continues via checkpoint-resume handoff — same WU, fresh context.

The ceilings are inclusive, matching the current checker. For example, a 20-file/50-call single-session estimate is compliant; warnings begin only above either ceiling.

The three strategy values above are the exact executable enum accepted by the sizing_estimate.strategy field on WU YAML (validated by wu:create and wu:brief; wu:brief --strict-sizing blocks non-compliant estimates):

sizing_estimate:
  estimated_files: 8
  estimated_tool_calls: 35
  strategy: single-session

decomposition is plan-only vocabulary for mapping one plan to several independently shippable outcomes. It is invalid on an active executable WU. Each resulting child WU declares one of the three strategies above. Terminal historical records remain readable.

Sizing Heuristics

Good Size Indicators

• Single clear outcome
• Can describe in one sentence
• Tests, code, and docs for that outcome all in the same WU

Too Big Indicators

• Multiple independent outcomes (not multiple steps toward one outcome)
• Description reads as a list of unrelated deliverables
• No clean stopping point; scope keeps widening

Too Small Indicators

• Cannot ship, review, or roll back alone
• Split by phase, layer, or artifact type rather than outcome
• Overhead exceeds value

When Splitting Is Justified

Split only when parts can ship, review, and roll back independently; different lanes/owners must deliver independent parts; a tracer-bullet or feature-flag pattern reduces real risk; or the work keeps widening without a clean stopping point.

Every proposed split must show independent ship, review, rollback, and safe partial value for the actual change:

Pattern	Required boundary	Safe partial value example
Tracer bullet	The first WU is a supported thin production path	A health probe proves authentication and transport before later operations
Layer split	A stable existing port makes each adapter independently useful	A read-only adapter serves a supported port; a later writer is optional value
UI/API split	The API has a real non-UI consumer and the UI can roll back alone	Automation consumes the API before the UI arrives
Migration/flag	The first WU produces evidence or value while both paths remain	Shadow execution records comparisons; a later WU switches traffic independently

If the real proposal cannot fill every boundary column, keep one WU and use a heavier execution strategy.

Caution

Anti-patterns the Consolidation Checklist rejects: splitting one behaviour change into a “tests WU” and a “code WU”; splitting one feature by field or form-section; splitting one flow by screen when the screens only ship together. Each fails the “ship/review/roll back independently” test.

When to Combine

Tiny WUs that fail the checklist get merged:

Too granular:

• WU-A: Add firstName field
• WU-B: Add lastName field
• WU-C: Add email field

Better:

• WU-X: Add user profile fields (firstName, lastName, email)

Sizing Exceptions

wu:create and wu:edit accept three bounded exception_type values. A name and arbitrary reason do not suppress sizing checks:

• docs-only — a single-session documentation WU may modify up to 40 prose docs artifacts in at most 50 whole-WU calls. Starlight MDX under apps/docs/src/content/docs/** qualifies. Templates, Astro/build config, and executable examples do not.
• shallow-multi-file — a uniform mechanical change across many files (each edit ≤5 lines, structurally identical) can stay single-session up to 50 modified files and 50 whole-WU calls. The reason records evidence of that uniformity. A 30-file change with unique logic does not qualify.
• review-audit — a process or documentation WU modifies prose report artifacts. Its declared strategy keeps the ordinary ceiling. Read coverage is recorded separately:

sizing_estimate:
  estimated_files: 2 # report and findings artifacts modified
  estimated_tool_calls: 80 # whole-WU effort
  strategy: checkpoint-resume
  exception_type: review-audit
  exception_reason: 'Two reports summarize 240 files read across bounded review scopes'

Creation-time advice warns without mutating the request; actual active-WU writes hard-validate exception applicability. wu:brief --strict-sizing also enforces numerical ceilings. The pack policy is shared by CLI, WU schema, and initiative admission.

The portable candidate-wu/v1 record retains its narrower original refinements for old-reader compatibility. It cannot encode checkpoint review-audit or all Starlight docs-only candidates. Those shapes require a future versioned candidate and containing plan before public admission cutover.

For review work, choose reviewer scopes from available host capacity. Keep each scope distinct and bounded by the normal session limits. There is no fixed minimum reviewer count.

If an audit discovers implementation work, promote a follow-up WU rather than stuffing the fix into the audit unless it remains the same coherent outcome.

Spikes Without a WU

For a narrow, read-only question (one dependency graph, one schema question) with a bounded budget (typically under 25 tool calls) whose answer immediately scopes the next WU, run a pre-phase audit without creating a WU and capture findings with pnpm mem:create --type discovery. If the investigation expands, create a review-audit WU instead. Research that produces a decision document is a normal WU (usually type: process or documentation with the review-audit exception) — there is no separate discovery WU type.

Dependencies

If WUs depend on each other, note it:

id: WU-201
title: Add theme toggle component
dependencies:
  - WU-200 # Needs theme context first

Execute in order, or work on independent WUs in parallel lanes.

Context Safety Triggers

If you hit ANY of these during a session, checkpoint and handoff:

• Token Limit: Context usage hits 50% (warning) or 80% (critical)
• Tool Volume: 50+ tool calls in current session
• File Volume: 20+ files modified in git status (also re-check cohesion)
• Performance Degradation: Redundant queries, forgotten context

Caution

When triggers fire: commit work, push branch, document progress in WU notes, then clear context and resume fresh. Handoff continues the same WU with a fresh context — it is never a reason to split the WU.

Sizing for Initiatives

An initiative needs two sizing passes: first validate each WU as one coherent outcome, then validate the active initiative graph. A list of locally valid WUs can still be over-fragmented.

Active Graph Default

• Treat 3-10 active WUs as a planning prompt, not a target or minimum. Zero, one, or two are valid when they are the coherent outcomes. Never pad the graph. Done or otherwise terminal history is excluded.
• Keep generic repairs and external prerequisites outside initiative membership; connect them with blocked_by.
• Above 10 active WUs, consolidate fragments, move an independent outcome to a focused successor initiative, or record a specific justification before dispatch.
• Gates and logical plan nodes do not each require a WU. Multiple nodes can map to one WU when they share a ship, review, and rollback boundary.

For plans with more than two proposed WUs, record two pairwise passes before creating IDs: a literal path/lane/dependency pass and an adversarial pass that assumes either WU lands alone. For every pair, record the outcome, lane, independent ship/review/rollback result, safe partial value, why a same-WU handoff is insufficient, and the merge/keep decision.

Caution

Strong under-sizing signals include the same lane and downstream blocker, a shared generated artifact, serial default-disabled fragments, repeated setup or verification, or a combined estimate that still fits the Complex tier. Phase names and directory boundaries alone are not independent user value.

Checkpoint-per-Wave

Each wave in an initiative is a batch of WUs that can execute in parallel. Between waves, the orchestrator checkpoints progress:

Wave 1: WU-A, WU-B (parallel) → checkpoint
Wave 2: WU-C, WU-D (parallel, depends on Wave 1) → checkpoint
Wave 3: WU-E (depends on Wave 2) → done

Individual WUs within an initiative follow the same cohesion rule and sizing thresholds as standalone WUs — the initiative handles coordination, not cohesion.

Initiative Sizing Rules

• Each WU in an initiative follows the standard cohesion rule and thresholds
• The orchestrator handles cross-WU coordination via memory signals
• Run the Consolidation Checklist over every proposed pair twice before IDs are allocated, and again whenever scope grows
• If a wave has more than 4-5 parallel WUs, re-check both the wave and the whole active graph before splitting it into sub-waves
• Use pnpm orchestrate:init-status --id INIT-XXX to monitor wave progress

Next Steps

• Work Units — WU structure and lifecycle
• Team Workflow — Collaborative sizing
• Initiatives — Multi-phase project coordination