Sizing WUs

One coherent outcome = one WU. Establish the delivery boundary, estimate modified artifacts and whole-WU calls, then choose a fitting execution strategy. Each session keeps its own safety limits. Thresholds select strategies; independent delivery boundaries justify splitting.

Design-First

Before sizing, use the design-first skill: question requirements, delete unnecessary work, simplify, speed up, automate last. Size only the work that survives the deletion pass.

For feature WUs and multi-WU initiatives, record design_validation in WU notes or the plan: what was considered for deletion, what was removed, the retained_reason, and how the skill’s 10 percent put-back rule was met. This is a design review requirement; there is no enforcing config key, flag, or schema field today.

Cohesion Rule

Describe the outcome in one sentence, then write acceptance criteria that prove it. Keep implementation, tests, documentation and required verification together when they must land together to deliver that outcome.

Before splitting, require independent ship, review, rollback and safe partial value for each proposed part. Multiple phases, directories, lanes, workers or sessions do not establish that boundary. A handoff changes the session, not the WU.

Shared files or a common root cause prompt a cohesion check; they do not by themselves prove that independent fixes must be merged. Conversely, separate files do not make tightly coupled fragments independently useful.

Unfinished acceptance stays in the current WU. Do not land a partial outcome and transfer its unmet criteria to a follow-up just because the session is long. Checkpoint and continue. A follow-up is appropriate for a separately useful outcome outside the agreed acceptance; record that boundary explicitly.

Consolidation Checklist

Before proposing more than two WUs, compare every pair and repeat after merges until no further merge qualifies:

1. Can either outcome be deleted? Delete it first.
2. Same lane and same outcome, or either part meaningless alone? Merge.
3. Split by phase or artifact type, or one change to a reviewer? Merge.
4. Same file/module? Usually merge; retain separate WUs only with evidence of independent delivery and a safe ownership/dependency plan.

Run this before presenting the WU list, allocating IDs or dispatching workers.

Initiative Graph Check

First size each WU, then check the active initiative graph:

• Delete unnecessary nodes before counting them. Gates and logical plan nodes are not automatically WUs; several may share one delivery boundary.
• 3-10 active WUs is a planning prompt, not a target or minimum. Zero, one or two are valid. Exclude terminal history; never pad the graph.
• Keep generic repairs and external prerequisites outside initiative membership; express their blocking relationship with blocked_by.
• Above 10 active WUs, replan before dispatch: consolidate fragments, move a genuinely separate outcome to a focused successor, or record a specific justification for retaining the graph. Worker count is a separate decision.

For more than two proposed WUs, preserve this pairwise evidence before IDs:

Pair	Outcome	Lane	Ships independently?	Reviews independently?	Rolls back independently?	Safe partial value?	Why handoff cannot preserve one WU	Decision

Use two passes: literal (paths, lanes, dependencies and acceptance), then adversarial (each part lands alone). Merge unusable, misleading or dormant fragments that require their companion immediately. Re-run when scope changes.

Shared downstream blockers, generated artifacts, repeated setup/verification and serial default-disabled fragments are prompts to consolidate. Neither a phase label nor a combined estimate inside Complex proves an independent outcome.

Strategy Decision List

1. Delete unnecessary work and establish the delivery boundary (Design-First and Cohesion Rule).
2. Estimate modified artifacts and whole-WU calls (Complexity Matrix).
3. Choose a strategy whose two ceilings both fit, applying only a qualified bounded exception (Exceptions). Use a heavier strategy when risk warrants it.
4. Plan bounded sessions and, where useful, distinct worker scopes. One lifecycle owner claims, briefs, preps and completes the WU; helpers do not run its lifecycle.
5. Apply session safety triggers during execution (Context Safety and Handoff). If scope grows, re-check cohesion and update the estimate through wu:edit.

Complexity Matrix

estimated_files counts artifacts expected to be modified, including tests and docs; it excludes files only read. estimated_tool_calls covers the entire WU, including resumed sessions and delegated work. Parallel execution does not reduce that whole-WU estimate.

Strategy tier	Modified-file ceiling	Whole-WU call ceiling	Strategy
Simple	20	50	single-session
Medium	50	100	checkpoint-resume
Complex	100	200	orchestrator-worker

Ceilings are inclusive, not targets or minimums. Choose the smallest fitting strategy unless uncertainty or coordination calls for a heavier one. Either dimension can raise the tier: 8 files/80 calls is Medium; 60 files/40 calls is Complex. A 20-file/50-call estimate fits Simple, but the session must still hand off at the 20-file or 50-call safety trigger.

Over ceiling means more than 100 files OR more than 200 calls. No executable strategy or current exception raises those limits. Re-check the estimate and remove unnecessary scope; split only independent outcomes. Keep an honest estimate: advisory surfaces warn, while strict briefing and admission reject numerical non-compliance. Relabeling the strategy does not create a larger tier.

Context percentage is a current-session safety signal, not a sizing field or an allowance to spend over 50% context in one worker. All strategies and exceptions retain the same session limits.

How to Estimate

1. Inspect the entry point and affected callers; list likely modifications, tests, documentation and required verification.
2. Estimate calls for discovery, implementation, verification and lifecycle. Include coordination, rebase/conflict recovery and an explicit uncertainty allowance; record the assumptions behind it.
3. Use comparable completed WUs when available. Large entry points (>500 lines or >50 branches), >20 symbol hits and unfamiliar code warrant closer investigation; read coverage alone does not increase estimated_files.
4. Round uncertain estimates up. If scoping takes more than 10 calls, bound the remaining question and consider the read-only pre-phase audit (Pre-Phase Audit).

Fixed familiarity multipliers are not measurements. Update estimates when the actual work changes; do not change them merely to silence a warning.

Delivery Cost and Parallelism

Compare strategies using claim-to-done median and p90 for comparable WUs, with size band, host load and sample/exclusion counts. Gate/command timings, review waits, retries and queueing explain that result; they are not substitutes for it. Report throughput alongside latency when comparing concurrency.

Repeated lifecycle overhead can reveal fragmentation; it cannot justify bundling independent outcomes. Choose worker count from available host capacity, WU dependencies, lane WIP/locks and bounded scopes. More workers alone is not an improvement. Existing efficiency/trajectory scores are advisory; see Flow Metrics & Analytics.

Exceptions

Exceptions change only the stated ceilings. All require exception_reason with concrete evidence and retain the Context Safety and Handoff rules.

Documentation-Only

docs-only permits 40 modified artifacts/50 whole-WU calls, with type: documentation, strategy: single-session and non-empty prose paths (for example Markdown or Starlight Markdown/MDX content).

Packaged templates, executable examples, Astro/build configuration and other code-owned assets do not qualify. A prose template may still qualify for normal documentation gates; that is separate from this sizing exception. For mixed surfaces, use normal lane/path validation and record the cross-surface reason.

Shallow Multi-File

shallow-multi-file permits 50 files/50 whole-WU calls, with strategy: single-session, an executable WU type and non-empty implementation paths. Every edit must be mechanically identical and no more than 5 lines, with no new functions, classes, control flow or structural changes; document that evidence.

Thirty files with distinct logic do not qualify. Size them normally: 30 files/80 calls is Medium, while 30 files/150 calls is Complex.

Review, Audit, and Exploration WUs

review-audit applies to process or documentation WUs whose modified outputs are prose reports/findings. Count those outputs, record read coverage separately and retain the ordinary ceilings of the selected strategy.

Define bounded review scopes and concrete questions, with file:line findings. For example, inspect a named component directory for missing loading/error states instead of asking to “review the frontend.” Use distinct, non-overlapping scopes when parallel review is useful; there is no minimum reviewer count. Capture out-of-scope implementation discoveries for triage.

Pre-Phase Audit (No WU)

A no-WU investigation is read-only, answers one narrow graph/file/schema question, has a bounded budget (typically fewer than 25 calls) and immediately scopes the next WU. It does not produce a standalone report. If it expands or becomes a durable deliverable, create a review/audit WU. Capture significant findings with pnpm mem:create --type discovery.

Sizing Contract

sizing_estimate:
  estimated_files: 8
  estimated_tool_calls: 80
  strategy: checkpoint-resume

Both estimates are non-negative integers; the strategy is one of the three executable values in the Complexity Matrix. An exception additionally requires exception_type (docs-only, shallow-multi-file, review-audit) and a non-empty exception_reason.

Set metadata through CLI tooling, never by editing WU YAML directly:

pnpm wu:edit --help
pnpm wu:edit --id WU-XXXX --estimated-files 8 --estimated-tool-calls 80 \
  --sizing-strategy checkpoint-resume

wu:create accepts the same flags; provide all three base sizing values when supplying its sizing tuple. Add metadata for delegated WUs, features expected to exceed Simple and initiative WUs. It remains optional for work comfortably inside Simple unless strict briefing is requested.

Boundary	What sizing enforces
Active-WU schema writes	Valid tuple, executable strategy and applicable bounded exception
Create/default brief advice	Warnings for numerical non-compliance; missing metadata is allowed
wu:brief --strict-sizing	Metadata required; applicability and both ceilings must pass
Internal initiative admission	Pack policy applicability and numerical ceilings

decomposition is plan-only vocabulary, never an active executable WU strategy. Terminal historical records retain compatibility. The checker does not prove semantic cohesion or mechanical edit uniformity; the review evidence must.

The shared pack policy is authoritative. Portable candidate-wu/v1 retains narrower refinements: checkpoint review audits and some Starlight docs-only candidates require a new candidate and containing-plan version for public admission, not an in-place widening of v1.

Decomposition Patterns

Use these only when the actual parts pass the Cohesion Rule’s independent-value test:

Pattern	Independently useful first outcome
Tracer bullet	A supported health probe proves authentication/transport
Layer split	A read-only adapter serves an existing stable port
UI/API split	A real automation consumer uses the API before the optional UI
Migration/flag	Shadow execution records useful comparisons before a traffic switch

For each, prove independent review and rollback, and safe partial value. A dormant flag or an unused interface alone does not establish that value. Tests/code/docs for one behavior stay together.

Context Safety and Handoff

Checkpoint and hand off when any trigger fires:

• 50% context (warning); 80% is critical: stop and resume fresh.
• 50+ tool calls in the current session.
• 20+ modified files in git status; also re-check cohesion.
• Repeated queries, forgotten constraints, wrong checkout or other degradation.
• The host is about to compact, clear or replace context.

From the claimed worktree, triage unread directed signals and preserve progress:

pnpm mem:checkpoint --wu WU-XXXX --note '<completed work and evidence>' \
  --next-steps '<remaining acceptance, risks and next action>'
pnpm wu:edit --id WU-XXXX --notes '<progress, verification and next steps>'
git status --short
git add -- <reviewed-path-1> <reviewed-path-2>
git commit -m 'checkpoint: progress on WU-XXXX'
pnpm wu:brief --id WU-XXXX

Read --help before first use of each command. Commit only reviewed paths in scope; publish the checkpoint branch through the normal workflow when the next session needs remote access. Generate the real post-claim brief after saving work, then stop. Continue the same WU in a fresh session from that brief, checkpoint and verified worktree.

Present the durable receipt unchanged to wu:prep, wu:done or wu:recover from its named authenticated session. A different presenter receives receipt_addressee_mismatch. If the receipt names the previous session, register your own scoped session with agent:session, use only its newly issued LUMENFLOW_AGENT_SESSION, and run a real wu:brief for the claimed WU to mint your receipt. Never transfer the previous agent’s session or fabricate evidence. Follow successor-receipt instructions after changed HEAD; expiry, protected-scope changes and replay fail closed.

At completion, run wu:prep in the worktree, then the exact command it prints from main. See the repository’s LUMENFLOW.md for cloud modes and receipt/recovery details. A checkpoint, re-brief or successful prep alone does not complete the WU.

Quick Examples

Scenario	Decision
1-file bug fix, 20 calls	single-session
Atomic feature, 8 files/80 calls	checkpoint-resume
Atomic change, 60 files/40 calls	orchestrator-worker
Prose docs, 30 files/40 calls	single-session with qualified docs-only
Identical import edits, 45 files/45 calls	single-session with qualified shallow exception
Audit reads 240 files, writes 2 reports/80 calls	checkpoint-resume with review-audit
Two failures in one required replay path	Keep the repair and acceptance in one WU
A shared file has two independently useful fixes	Separate WUs can pass the boundary test
Required target unmet after a long session	Checkpoint and continue the same WU

Next Steps

• Work Units — WU structure and lifecycle
• Team Workflow — Collaborative delivery
• Initiatives — Dependency-aware coordination
• Gates — Verification and scoped test execution