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. Agents operate in context windows and tool calls, not clock time.

| Complexity | Files | Tool Calls | Context Budget | Strategy (sizing_estimate.strategy) | | ------------- | ----- | ---------- | -------------- | ------------------------------------------------------ | | Simple | <20 | <50 | <30% | single-session | | Medium | 20-50 | 50-100 | 30-50% | checkpoint-resume | | Complex | 50+ | 100+ | >50% | orchestrator-worker or checkpoint-resume if atomic | | Oversized | 100+ | 200+ | — | Re-check cohesion; decomposition only if non-atomic |

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 strategy values above are the exact 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

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.

Pattern A: Tracer Bullet (Risk Reduction)

Best for: New integrations, unproven libraries.

| WU | Title | | ---- | ---------------------------------- | | WU-A | Port + mock adapter + E2E skeleton | | WU-B | Real adapter + error handling |

Pattern B: Layer Split (Independently Reviewable)

Best for: Large backend features where each layer ships and reviews alone.

| WU | Title | | ---- | ----------------------------------- | | WU-A | Ports + application + unit tests | | WU-B | Infrastructure adapters + int tests |

Pattern C: UI/Logic Split (Lane Separation)

Best for: Full-stack features where different lanes ship independently.

| WU | Title | Lane | | ---- | --------------------- | ---- | | WU-A | API + DB + backend | Core | | WU-B | Components + UI state | UI |

Pattern D: Feature Flag (Phased Rollout)

Best for: High-risk refactoring, breaking changes needing rollback.

| WU | Title | | ---- | --------------------------------------- | | WU-A | New logic behind ENABLE_NEW=true flag | | WU-B | Remove flag + delete old code |

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 exception_type values that document intentional threshold overruns:

• docs-only — documentation WUs get relaxed file thresholds (Simple up to ~40 docs files) because docs carry no test/type/lint dependency graph. Applies only when the WU type is documentation and it touches nothing under apps/**, packages/**, or tools/**.
• shallow-multi-file — a uniform mechanical change across many files (each edit ≤5 lines, structurally identical) can stay single-session. A 30-file change with unique logic per file does not qualify.
• review-audit — read-heavy audit work may read many files while modifying none or few:

sizing_estimate:
  estimated_files: 80 # files read/reviewed, not necessarily modified
  estimated_tool_calls: 180
  strategy: orchestrator-worker
  exception_type: review-audit
  exception_reason: 'Wide read-only audit split across non-overlapping reviewers'

wu:create/wu:edit’s advisory sizing check and the persisted WU YAML schema both accept all three values, so sizing_estimate.exception_type can be set to docs-only, shallow-multi-file, or review-audit in any WU spec.

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

When working within an initiative, sizing changes because the orchestrator manages wave-based execution with checkpoints between waves.

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
• If a wave has more than 4-5 parallel WUs, run the Consolidation Checklist over the wave 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