model-routing git:20260606.ab44b47A

Immutable. This exact content is served forever at /api/v1/blob/a7870fb7421eb420.

---
name: model-routing
description: Use when selecting a model for a new task or subagent, deciding whether to escalate after a failed attempt, or designing a multi-agent pipeline with mixed task complexity.
---

# Model Routing

Choose the right model tier before starting a task. Overusing a capable model wastes cost and context. Underusing it produces lower quality on complex work.

## When to Use

- Selecting a model for a new task or subagent
- Deciding whether to escalate after a failed attempt
- Designing a multi-agent pipeline with mixed task complexity

## Tier Definitions (vendor-neutral)

| Tier | Typical examples | Task profile |
|------|-----------------|--------------|
| **Fast** | Haiku, GPT-4o-mini, Gemini Flash | Mechanical, deterministic, narrow |
| **Standard** | Sonnet, GPT-4o, Gemini Pro | General implementation and review |
| **Deep** | Opus, o1, Gemini Ultra | Architecture, security, root-cause, release |

Use your provider's current recommended model for each tier. Do not hard-code model IDs in documentation or scripts; reference tiers instead.

## Routing Table

### Fast tier

Use when ALL of:
- Single file or single operation
- Output is deterministic (rename, format, classify, generate boilerplate)
- No ambiguity in the task description
- Low blast radius on failure (easy to retry or revert)

Examples: rename a variable, convert a data format, generate a changelog entry, classify issue severity.

### Standard tier

Use when ANY of:
- Multi-file change with known scope
- Standard implementation task (add a feature, fix a bug, write tests)
- Code review of a bounded change
- Refactor with clear before/after contract

This is the **default**. When unsure, use Standard.

### Deep tier

Use when ANY of:
- Architecture or system design decision
- Security audit or threat model
- Root-cause analysis with no clear reproduction
- Pre-release verification across a large surface
- Task requires reasoning across many files simultaneously
- Two Standard attempts failed with no clear progress

Do not use Deep speculatively. It is expensive and slower.

## Escalation Rule

**Try Standard first.** Escalate to Deep only after Standard fails with a clear reasoning gap — not just a wrong answer. A wrong answer from Standard often means the task needs more context, not a more capable model.

Do not escalate because of anxiety about getting it right. Escalate because the attempt revealed a complexity that a smaller model cannot handle.

## Session Discipline

- Start a new session after a major phase transition (research → implement → test)
- Compact context after finishing research before starting implementation
- Do not carry debugging traces into an implementation session
- Short-lived subagents default to Fast or Standard depending on task type

## Cost Tracking

Record per task:
- Tier used
- Approximate token count
- Number of retries
- Success/escalated/failed

Use this to calibrate your routing decisions over time. If Standard succeeds > 90% of the time on a task type, that task does not need Deep.

## Anti-Patterns

- **Pre-escalation**: Using Deep on a task that hasn't been tried at Standard
- **Anxiety escalation**: Using Deep because the task feels important, not because it's complex
- **Under-routing**: Using Fast for a multi-file refactor and then retrying three times
- **Model pinning**: Hard-coding specific model IDs in configs instead of tier references

## Verification

- [ ] Tier was chosen from the routing table before the task started — Standard by default when unsure
- [ ] Deep was used only for a listed Deep criterion or after a Standard attempt exposed a reasoning gap
- [ ] No specific model IDs were hard-coded — tier references only
- [ ] Tier, retries, and outcome were recorded for future calibration