docs/model-selection-playbook.md

# Model Selection Playbook

> Guidance for choosing models by phase and task type.
> 
> **No model is required.** These are recommendations, not requirements.

---

## Selection by Phase

### Planning & Architecture

**Recommended capabilities:**
- Extended reasoning / thinking mode
- Large context window (analyze multiple files)
- Strong at structured output (specs, plans)

**Why:** Planning requires understanding full system context and making architectural decisions.

**Examples:** Models with "thinking" or "reasoning" modes, larger context variants.

---

### Code Implementation

**Recommended capabilities:**
- Fast iteration speed
- Good at code completion
- Tool/function calling (for verification commands)

**Why:** Implementation involves many small changes with frequent verification cycles.

**Examples:** Speed-tier models, code-specialized variants.

---

### Refactoring

**Recommended capabilities:**
- Large context window (see before/after)
- Pattern recognition
- Consistent style application

**Why:** Refactoring requires maintaining consistency across large code changes.

**Examples:** Standard or long-context variants.

---

### Debugging

**Recommended capabilities:**
- Extended reasoning (hypothesis generation)
- Good at reading stack traces
- Context for error patterns

**Why:** Debugging requires hypothesis testing and pattern matching.

**Examples:** Reasoning-focused models.

---

### Code Review

**Recommended capabilities:**
- Large context (review full PR diff)
- Security pattern knowledge
- Style consistency checking

**Why:** Review requires seeing both code and context together.

**Examples:** Long-context variants.

---

## Capability Tiers

| Tier | Characteristics | Best For |
|------|-----------------|----------|
| **Fast** | Quick responses, lower cost | Implementation, iteration |
| **Standard** | Balanced speed/quality | Most tasks |
| **Reasoning** | Extended thinking, slower | Planning, debugging, architecture |
| **Long-context** | >100k tokens | Review, refactoring |

---

## Anti-Patterns

❌ **Using reasoning models for simple edits** — Overkill, slow, expensive

❌ **Using fast models for architecture** — Insufficient depth for complex decisions

❌ **Ignoring context limits** — Leads to quality degradation

❌ **Forcing a specific model** — Breaks model-agnosticism

---

## Model Switching Mid-Session

**When to switch:**
- Context is getting polluted (approaching 50%)
- Task type changes significantly (planning → implementation)
- Current model struggling with task type

**How to switch:**
1. Create state snapshot
2. Update STATE.md with current position
3. Start fresh session with appropriate model
4. Load STATE.md to resume

---

## GSD Model-Agnostic Principle

GSD works with any capable LLM. The methodology compensates for model differences through:

1. **Structured plans** — Reduce ambiguity
2. **Explicit verification** — Catch errors regardless of model
3. **State persistence** — Enable model switching
4. **Fresh context** — Prevent accumulation issues

Choose models based on task needs, not methodology requirements.

---

*See PROJECT_RULES.md for canonical rules.*
*See docs/runbook.md for operational procedures.*