reasoning-models v1.0.0A

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

---
name: "reasoning-models"
description: 'Use reasoning / thinking models (OpenAI o-series, Anthropic extended thinking, DeepSeek R1, Gemini Thinking) effectively. Covers when to choose reasoning vs fast models, prompt patterns for reasoners, reasoning_effort / thinking budget controls, structured outputs with reasoning, cost/latency trade-offs, and combining reasoners with fast models.'
metadata:
  author: "Frontier"
  version: "1.0.0"
  created: "2026-04-30"
  updated: "2026-04-30"
compatibility:
  frameworks: ["openai", "anthropic", "azure-foundry", "deepseek", "gemini"]
  languages: ["python", "typescript", "csharp"]
---

# Reasoning Models

> **Purpose**: Get reliable answers from reasoning models without overspending or stalling on tasks that do not need them.

---

## When to Use This Skill

- Choosing between a reasoning model (o3, GPT-5 thinking, Claude extended thinking, DeepSeek R1, Gemini Thinking) and a fast model
- Setting `reasoning_effort` (low / medium / high) or thinking-token budgets
- Designing prompts for reasoning models (different from chat models)
- Combining reasoners (planner) with fast models (executor)
- Diagnosing high cost or latency on reasoning calls

## When NOT to Use a Reasoning Model

- Routine extraction, summarization, classification -- a fast model is cheaper and faster
- Strict latency budget (<2s end-to-end) -- reasoning models add seconds
- Tool-use-heavy loops where each turn is short -- fast model + scaffolding is usually better

---

## Decision Tree

```
Is the task hard? (multi-step reasoning, math, planning, code refactor across files,
                   ambiguous spec, agent strategy)
+- No  -> Fast model (gpt-5, claude-haiku-4.5, gemini-2.5-flash)
+- Yes -> Reasoning model
        +- Need fast feedback loop?  -> Reasoning effort = low / medium
        +- Quality > latency?         -> Reasoning effort = high
        +- Multi-turn tool use?       -> Often: fast model with strong scaffold beats a reasoner alone
```

---

## Prompt Patterns That Differ for Reasoners

| Pattern | Chat / Fast Model | Reasoning Model |
|---------|-------------------|-----------------|
| Chain-of-thought ("think step by step") | Helpful | Counterproductive (model already reasons) |
| Few-shot examples | Often improves | Use sparingly; can over-anchor |
| Long detailed system prompts | Often needed | Often shorter prompts work better |
| Strict output format | Add explicit schema | Use Structured Outputs / response_format |
| Self-critique loops | Sometimes helps | Built-in; do not duplicate |

Rule of thumb: give reasoning models the **goal** and the **constraints**, not the procedure.

---

## Cost and Latency

Reasoning tokens are billed and counted toward context. Plan for:

- Latency: 2x-30x a fast model on the same task
- Cost: hidden reasoning tokens often exceed visible output tokens
- Context: reasoning trace can consume 5-50K hidden tokens

Controls:

- OpenAI: `reasoning.effort = low | medium | high`
- Anthropic extended thinking: `thinking.budget_tokens` (cap)
- Azure Foundry: model-specific `reasoning_effort`
- Gemini Thinking: `thinking_config.thinking_budget`

Always set a budget cap in production to bound runaway cost.

---

## Reasoner + Executor Pattern

A common production pattern:

```
[Reasoning Model: planner]
   - Reads goal, constraints, evidence
   - Emits structured plan (steps, tool calls, success criteria)
        |
        v
[Fast Model: executor]
   - Executes each step, calls tools
   - Returns results
        |
        v
[Reasoning Model: judge]
   - Evaluates result against criteria
   - Decides done / replan / abort
```

Benefits: reasoner is called 1-3 times, executor handles N tool turns cheaply.

---

## Structured Outputs

Reasoning models support Structured Outputs / `response_format: json_schema`. Use it -- do not parse free-form text from a reasoner.

For Anthropic extended thinking, the `<thinking>` block is separate from the answer -- consume `assistant` content and ignore `thinking` content unless you have a reason to log it (audit, eval).

---

## Anti-Patterns

| Anti-Pattern | Why Bad |
|--------------|---------|
| "Think step by step" in the prompt | Doubles work; model already reasons |
| Asking the reasoner for many tool calls per turn | Reasoning models are slow per call; use a fast executor |
| No budget cap | Cost and latency runaway in agent loops |
| Long few-shot blocks | Over-anchors; reasoners infer better with fewer examples |
| Logging full thinking traces by default | PII risk; stores hidden chain-of-thought |

---

## Skills to Load Alongside

| Need | Skill |
|------|-------|
| Prompt design fundamentals | `prompt-engineering` |
| Cost / latency monitoring | `agent-observability` |
| Selecting a model per task | `llm-gateway-and-routing` |
| Quality measurement | `ai-evaluation` |
| Multi-step planning architectures | `multi-agent-orchestration` |

## References

- OpenAI o-series and reasoning_effort docs
- Anthropic extended thinking guide
- DeepSeek R1 paper and serving notes
- Gemini Thinking documentation