Guidance for choosing models by phase and task type.
No model is required. These are recommendations, not requirements.
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.
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.
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.
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.
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.
| 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 |
❌ 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
When to switch:
- Context is getting polluted (approaching 50%)
- Task type changes significantly (planning → implementation)
- Current model struggling with task type
How to switch:
- Create state snapshot
- Update STATE.md with current position
- Start fresh session with appropriate model
- Load STATE.md to resume
GSD works with any capable LLM. The methodology compensates for model differences through:
- Structured plans — Reduce ambiguity
- Explicit verification — Catch errors regardless of model
- State persistence — Enable model switching
- 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.