# 5. Lazy-loaded phase docs with per-phase token budget

**Status:** Accepted · 2025

## Context

Phase specs are model-facing instructions. When the orchestrator (Claude Code
or Copilot CLI) enters a phase, it reads the phase doc and follows the steps.
If all phase docs were loaded up front, the context window would fill with
instructions for phases not yet relevant, leaving less room for the actual
code being worked on.

Additionally, phase docs are the easiest part of the pipeline to inflate
accidentally - examples, prose, caveats pile up. Without a budget, phase
docs silently grow until they push useful content out of context.

## Decision

Each phase doc is a separate file (`pipeline/commands/multi-agent/refs/phases/
phase-N-*.md`) that the orchestrator loads only when entering that phase.

`pipeline/schemas/token-budget.json` defines `warn` and `max` thresholds per
phase. The `smoke-token-budget.sh` check approximates token count for each
phase doc and fails the build if any phase exceeds its `max`.

Current budgets (v3.5.0):

- Phase 0: warn 3500 / max 4000 (INIT is interactive + token-heavy)
- Phase 1: warn 1200 / max 1500
- Phase 2: warn  800 / max 1000
- Phase 3: warn 1500 / max 1800
- Phase 4: warn 1800 / max 2200 (triage + 3-model review is verbose)
- Phase 5: warn  600 / max  800
- Phase 6: warn 2400 / max 2800 (commit + PR + issue body update)
- Phase 7: warn 1800 / max 2200

Total phase doc budget: 14,300 tokens across 8 phases, loaded incrementally.

## Consequences

Positive:

- Context window stays available for the code under review.
- Budgets surface "this phase is getting bloated" early (warn) before they
  become blocking (max).
- A PR that inflates a phase doc past `max` fails CI - hard forcing function
  against doc rot.

Negative:

- Cross-phase references require either duplication (bad) or jumping back to
  a phase's doc (imperfect). Mitigated by keeping phase docs self-contained
  and putting cross-cutting rules in `refs/rules.md`, loaded once at Phase 0.
- The token estimator is approximate (character-count based); true token
  cost varies by model. Budgets err on the generous side to avoid false
  failures.

## Alternatives Considered

**Single monolithic phase doc:** what the pipeline started with. Rejected
after `modes.md` + phase docs added up to >8K tokens just for instructions.

**Dynamic budget (load until context fills):** too lossy. Some phases
(Phase 4 triage) would silently lose content mid-instruction.

**Per-model budgets (Opus gets bigger, Sonnet gets smaller):** over-engineered
for current needs. Same budgets work across the models the pipeline uses
today. Reconsider if per-model skew becomes measurable.