Sizing WUs

Right-sizing WUs is critical for flow. Too big = stuck. Too small = overhead.

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
Simple	<20	<50	<30%	Single Session
Medium	20-50	50-100	30-50%	Checkpoint-Resume
Complex	50+	100+	>50%	Orchestrator or Split
Oversized	100+	200+	—	Must Split

Tip

If you can’t complete a WU in a single session, it’s too large. Split it using the patterns below.

Sizing Heuristics

Good Size Indicators

• Single clear outcome
• Touches 1-5 files
• One test file added/modified
• Can describe in one sentence
• No “and then…” in the description
• Estimated <50 tool calls

Too Big Indicators

• Multiple outcomes
• Touches 10+ files
• Requires multiple test suites
• Description has multiple paragraphs
• Contains “and”, “also”, “plus”
• Estimated 100+ tool calls

Too Small Indicators

• Just a config change
• Single line fix
• No tests needed
• Overhead exceeds value

Splitting Strategies

By Layer

Too big: “Add user preferences feature”

Split:

• WU-100: Add preferences API endpoint (Core)
• WU-101: Add preferences database schema (Infra)
• WU-102: Add preferences UI panel (UI)

By Behavior

Too big: “Add form validation”

Split:

• WU-110: Add email format validation
• WU-111: Add password strength check
• WU-112: Add form error display

By User Action

Too big: “Add checkout flow”

Split:

• WU-120: Add cart summary view
• WU-121: Add payment method selection
• WU-122: Add order confirmation

Splitting Patterns

Pattern A: Tracer Bullet (Risk Reduction)

Best for: New integrations, unproven libraries.

WU	Title	Tool Calls
WU-A	Port + mock adapter + E2E skeleton	~30
WU-B	Real adapter + error handling	~40

Pattern B: Layer Split (Architectural)

Best for: Large backend features, hexagonal architecture.

WU	Title	Tool Calls
WU-A	Ports + application + unit tests	~40
WU-B	Infrastructure adapters + int tests	~40

Pattern C: UI/Logic Split (Lane Separation)

Best for: Full-stack features.

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.

WU	Title	Tool Calls
WU-A	New logic behind ENABLE_NEW=true flag	~50
WU-B	Remove flag + delete old code	~30

When to Combine

Sometimes tiny WUs can be combined:

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)

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
• 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.

Discovery WUs

When uncertain, create a discovery WU first:

id: WU-299
title: Spike - evaluate auth libraries
type: discovery
acceptance:
  - Document pros/cons of 3 auth libraries
  - Recommend one with rationale
  - No code changes (research only)

Discovery WUs produce decisions, not code. They unblock future implementation WUs.

Review-Audit WUs

Read-heavy audit work is different from implementation work. A review/audit WU may read many files while modifying none or only a small report. Use the review-audit sizing exception when the outcome is an audit, triage, or recommendation rather than direct code change.

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 and wu:edit accept docs-only, shallow-multi-file, and review-audit as sizing exception types. If the audit discovers implementation work, promote a follow-up WU rather than stuffing the fix into the audit unless it remains the same coherent outcome.

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

This means individual WUs within an initiative should still be Simple or Medium sized. The initiative handles the coordination — don’t try to make individual WUs larger because “the initiative will manage it.”

Initiative Sizing Rules

• Each WU in an initiative follows standard sizing thresholds
• The orchestrator handles cross-WU coordination via memory signals
• If a wave has more than 4-5 parallel WUs, consider splitting 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