Task Complexity

Task Complexity

Foundry adapts its ceremony to match the task. Small tasks skip heavyweight processes; large tasks get the full treatment.

Why Complexity Matters

A one-file bug fix doesn't need a design document, architecture review, or multi-split branching strategy. Forcing that ceremony wastes time and tokens. Conversely, a new API spanning 15 files across 3 components needs that ceremony — skipping it leads to incoherent code.

Foundry's complexity system makes this automatic.

Classification

Crucible assesses complexity during Phase 1 (Intake) based on:

Signal	Small	Large
Estimated files	≤ 5	> 5 or multiple components
Splits	Single split likely	Multiple splits needed
Scope	Bug fix, config change, simple feature	New APIs, services, data models
Cross-cutting	Single module	Multiple modules/layers

The classification is proposed to the user for confirmation:

Complexity assessment: SMALL
Reasoning: Single enum standardization across 3 billing policy files.
This means: design doc will be skipped, architecture doc won't be required.
Is this correct? [yes / change to large]

What Changes

Aspect	Small Task	Large Task
Design document	❌ Skipped entirely	✅ Generated by 3 models
Architecture doc	❌ Not required by Forge	✅ Required — Forge blocks without it
Plan verifier	✅ Runs every iteration	✅ Runs every iteration
Design verifier	❌ Skipped	✅ Runs at split completion
Architecture verifier	❌ Skipped	✅ Runs at split completion
Deep review	✅ Runs (lighter)	✅ Runs (full)
Build gate	✅ Runs	✅ Runs

Token Impact

Small tasks use roughly 40–60% fewer tokens than large tasks because:

• No design doc generation (3 models × N rounds)
• No design/architecture verification passes
• Typically fewer splits and iterations

How It Flows Through the System

1. Crucible (Planning)

Phase 1 → Assess complexity → User confirms
Phase 3 → Fleet dispatch:
           Small: plan-drafter only (3 models)
           Large: plan-drafter + design-drafter (3 models each)
Phase 4 → Convergence:
           Small: plan only
           Large: plan + design doc
Phase 6 → Output:
           Small: plan.md only
           Large: plan.md + design-doc.md

2. Plan Template

The plan-drafter writes the classification into the plan:

## Complexity
Classification: small
Reasoning: Single enum standardization across 3 billing policy files.
Impact: Design document skipped. Architecture verification skipped.

3. Forge (Execution)

Forge reads the ## Complexity section from the plan:

Phase 2 → Locate documents:
           Small: plan.md + architecture doc (optional)
           Large: plan.md + design-doc.md + architecture doc (required)
Phase 4 → Readiness gate:
           Small: Missing design doc → OK
           Large: Missing design doc → BLOCK
           Large: Missing architecture doc → BLOCK
Phase 6 → Per-split RALPH loop:
           Small: plan-verifier only
           Large: plan-verifier + design-verifier + architecture-verifier
Phase 7 → Deep review:
           Both: 3 adversarial agents review the diff

4. Scribe (Logging)

The scribe includes complexity in every log entry:

### Iteration 2 — Split 1
- **Complexity:** small ⚡ (design/arch verifiers skipped)
- **Plan-verifier:** ✅ PASS (0 issues)
- **Files modified:** BillingPolicyType.cs, BillingPolicyHelper.cs

The ⚡ emoji signals reduced ceremony — anyone reading the log knows verifiers were intentionally skipped, not accidentally missed.

Overriding Complexity

The user can override Crucible's assessment:

• Crucible proposes small, user says large → Full ceremony applies
• Crucible proposes large, user says small → Reduced ceremony, with a caution message

There's no way to change complexity mid-Forge — it's baked into the plan. If Forge discovers the task is more complex than planned, it logs a warning but continues with the plan's classification.

Backward Compatibility

Plans created before v1.4.0 (when complexity was added) don't have a ## Complexity section. Forge handles this gracefully:

• Missing ## Complexity → defaults to large (full ceremony)
• Missing complexity in forge-state.md → defaults to large

This ensures older plans still work without modification, with the conservative default of maximum verification.