pick-model · diff
git:20260923.7852cb4 to git:20261007.83cf275
96 added, 188 removed. Audit A to A.
---
name: pick-model
- description: Recommend optimal Claude model (haiku/sonnet/opus) for a task. Use when user asks "which model", "pick model", "model for", or before starting costly/complex tasks. Covers tech and non-tech tasks.
+ description: Recommend the cheapest Claude model tier (Haiku, Sonnet, Opus) that still meets a task's quality bar, using a task-type matrix plus complexity escalators (scope, stakes, ambiguity, stakeholders). Use when asked "which model", "pick model", "model for", or before starting a costly task. Covers technical, business, creative work.
model: haiku
- context: main
---
# Pick Model
- Classify user's task → recommend optimal model with reasoning.
-
- ## Instructions
+ Classify the task, apply the escalators, then recommend the cheapest Claude tier that meets the quality requirement.
- 1. Parse task description from `$ARGUMENTS`
- 2. Classify against decision matrix below
- 3. Output recommendation using format template
+ ## Mindset
- ## Decision Matrix
+ - Right-size and do not default up. Keep to the cheapest tier that meets the quality bar. Escalating after a failed attempt costs one retry; an Opus habit costs every call.
+ - Judge reasoning demand, not volume. Pass a long document to a summariser at the same tier as a short one.
+ - Name tiers (fast, balanced, reasoning) before model names. Model names are retired and renamed; tier meaning lasts.
+ - Escalate with a stated reason. Always name the signal that moved the tier.
- ### Technical Tasks
+ ## When to Use
- | Model | When to Use |
- |---|---|
- | 🟢 **Haiku** | Simple transforms, formatting, regex, typo fix, status query, template fill, data extraction, factual lookup (no reasoning), file conversion |
- | 🟡 **Sonnet** | Single-file coding, bug fix, code review, moderate debugging, test writing, PR review, standard refactoring, technical docs, API integration (known patterns) |
- | 🔴 **Opus** | Multi-file refactor (3+ files), architecture/design decisions, complex debugging (multi-system), framework migration, security audit, novel algorithm design, system design with trade-offs |
+ - Use it when a user asks which model fits a task, before the work starts.
+ - Use it when an agent must assign a model to a sub-task without a human in the loop.
+ - Use it when a pipeline or batch job overspends on a frontier model for simple work.
+ - Use it when the cost against capability trade-off must be explicit, for example in production routing.
- ### Business & Strategy Tasks
+ ## When Not to Use
- | Model | When to Use |
- |---|---|
- | 🟢 **Haiku** | Summarization (<2K words), data extraction, status reports, simple translations, template filling, meeting notes formatting |
- | 🟡 **Sonnet** | Content creation (blog, email, docs), research summaries, competitive analysis, standard business writing, persuasive proposals, marketing copy, customer communications |
- | 🔴 **Opus** | Strategic planning, business model design, M&A analysis, organizational design, change management plans, competitive strategy, market entry decisions, crisis response, stakeholder management (competing interests), long-form reports (>2K words), executive presentations with nuance |
+ - Do not use it when infrastructure or an explicit user instruction already fixes the model.
+ - Do not use it once the task is finished, because the choice is moot.
+ - Do not use it for cross-vendor comparisons or live pricing, which this skill does not hold.
+ - Do not use it when a fine-tuned or domain-specific model decides the outcome, not the tier.
- ### Creative & Analysis Tasks
+ ## Procedure
- | Model | When to Use |
- |---|---|
- | 🟢 **Haiku** | Basic formatting, simple data viz suggestions, straightforward categorization |
- | 🟡 **Sonnet** | Creative writing, brainstorming (single framework), persona development, user research synthesis, A/B test analysis, survey analysis |
- | 🔴 **Opus** | Multi-framework brainstorming (SCAMPER + Starbursting + trade-off analysis), cross-session pattern detection, bias identification, retrospective analysis, ethical reasoning, strategic foresight, scenario planning |
+ 1. Read the task from `$ARGUMENTS`. Ask for it when the argument is empty.
+ 2. Match the task type to a base tier in the matrix below. Match what the task demands, not how long it is.
+ 3. Run every escalator check below. Move up exactly one tier when any escalator fires, capped at Opus.
+ 4. Apply the tie-breaks below to a borderline call.
+ 5. Adjust for cost and latency only after the tier is settled.
+ 6. Make the recommendation in the output template below. Always name the escalator or matrix row that decided it.
- ### Commands, Skills, Agents
+ ### Base tier by task type
- | Model | When to Use |
+ | Tier | Typical work |
|---|---|
- | 🟢 **Haiku** | Simple conversions (PDF, EPUB), format checks, simple utilities, minimal reasoning |
- | 🟡 **Sonnet** | Standard workflows, context management, serialization, most skills/commands (DEFAULT) |
- | 🔴 **Opus** | Strategic analysis (brainstorm, retrospectives), multi-framework reasoning, high-stakes decisions, pattern detection across sessions |
-
- ## Complexity Escalators
-
- Upgrade one tier if task has ANY of these signals:
-
- ### Technical Escalators
- - **Ambiguity**: Underspecified requirements, multiple valid interpretations → +1 tier
- - **Scope**: Affects 3+ files/systems/components → +1 tier
- - **Stakes**: Production system, security, data-loss risk, regulatory compliance → +1 tier
- - **Novelty**: No established pattern, novel algorithm, cutting-edge tech → +1 tier
+ | 🟢 **Haiku** (fast) | Typo fixes, formatting, regex, extraction, templated fills, file conversion, factual lookup, summaries under 2K words |
+ | 🟡 **Sonnet** (balanced) | Single-file code and bug fixes, code review, tests, standard refactors, technical and business writing, research summaries (the default for skills and commands) |
+ | 🔴 **Opus** (reasoning) | Multi-file refactors, architecture, multi-system debugging, security audits, strategy, long-form reports, multi-framework analysis |
- ### Business Escalators
- - **Multiple stakeholders**: Competing interests, need to balance trade-offs → +1 tier
- - **Strategic impact**: Long-term consequences, irreversible decisions, organizational change → +1 tier
- - **Political sensitivity**: Layoffs, restructuring, executive communications, crisis → +1 tier
- - **Cross-functional**: Requires synthesis across domains (tech + business + legal) → +1 tier
+ Read [the full matrix](references/decision-matrix.md) for technical, business, creative and command or agent tasks.
- ### Cognitive Escalators
- - **Pattern detection**: Requires analyzing trends across multiple data points/sessions → +1 tier
- - **Bias identification**: Needs to spot blindspots, cognitive biases, assumptions → +1 tier
- - **Ethical reasoning**: Moral ambiguity, fairness considerations, unintended consequences → +1 tier
- - **Multi-framework**: Applying 2+ analytical frameworks simultaneously → +1 tier
+ ### Escalators
- **Cap at Opus.** If multiple escalators apply, still cap at Opus (don't "double upgrade").
+ Move up one tier when the task shows any of these signals.
- ## Decision Guidance
+ - Check **ambiguity**: requirements are underspecified or have several valid readings.
+ - Check **scope**: the change spans 3 or more files, systems or components.
+ - Check **stakes**: production, security, data loss or regulatory exposure.
+ - Check **novelty**: no established pattern exists.
+ - Check **stakeholders**: competing interests need balancing.
+ - Check **irreversibility**: strategic, long-term or organisational consequences.
+ - Check **sensitivity**: layoffs, executive messaging, crisis response.
+ - Check **synthesis**: the work crosses domains such as tech, business and legal.
+ - Check **cognition**: pattern detection across sessions, bias spotting, ethical reasoning or two or more analytical frameworks at once.
- **When uncertain between two models:**
- - **Haiku vs Sonnet**: Does it require *any* reasoning/judgment? → Sonnet
- - **Sonnet vs Opus**: Are there trade-offs to balance or multiple valid approaches? → Opus
- - **Default rule**: When in doubt, go one tier up (better quality > cost savings)
+ See [escalators](references/escalators.md) for edge cases and borderline readings.
- **Quality vs Cost trade-offs:**
- - **Cost-sensitive**: Batch processing, exploratory work, drafts → prefer lower tier
- - **Quality-critical**: Customer-facing, executive, production, irreversible → prefer higher tier
- - **Iteration-friendly**: Can easily retry with higher tier if insufficient → start lower
+ ### Tie-breaks
- **Speed considerations:**
- - Haiku is ~3-5x faster than Sonnet, ~10x faster than Opus
- - For latency-sensitive workflows (UI feedback, real-time), prefer Haiku/Sonnet
- - For batch/async work, speed matters less than quality
+ - Choose Sonnet over Haiku when the task needs any judgement.
+ - Choose Opus over Sonnet when trade-offs must be balanced or several valid approaches exist.
+ - Go one tier up when the output is customer-facing, production or irreversible.
+ - Start one tier lower when a retry is cheap, as in drafts, batch runs and exploration.
## Output Format
- ```
- [emoji] **[Model]** — [1-line reason]
+ ```text
+ [emoji] **[Model]**: [one-line reason naming the deciding signal]
- 💰 Cost: [lowest/medium/highest] | ⚡ Speed: [fastest/medium/slowest]
+ Cost: [lowest|medium|highest] | Speed: [fastest|medium|slowest] | Confidence: [high|medium|low]
- 💡 [Optional: "Consider [other model] if [condition]"]
+ Tip: [only when a cheaper or stronger tier fits a stated condition]
```
- **Example output:**
- ```
- 🔴 **Opus** — Multi-stakeholder strategic decision with trade-offs
+ ```text
+ 🔴 **Opus**: refactor touches 15 files and changes the auth architecture (Scope escalator)
- 💰 Cost: highest | ⚡ Speed: slowest
+ Cost: highest | Speed: slowest | Confidence: high
- 💡 Consider Sonnet if this is exploratory (draft) rather than final recommendation
+ Tip: Sonnet is enough if the scope shrinks to 2 files after exploration.
```
- ## Examples
-
- ### Technical Tasks
-
- | Task | Recommendation | Rationale |
- |---|---|---|
- | "fix typo in README" | 🟢 **Haiku** | Trivial single edit, no reasoning |
- | "convert PDF to markdown" | 🟢 **Haiku** | Simple conversion, no decisions |
- | "debug flaky integration test" | 🟡 **Sonnet** | Single-system debugging, moderate reasoning |
- | "refactor auth across 15 files" | 🔴 **Opus** | Multi-file (3+ escalator) + architectural decisions |
- | "design database schema for e-commerce" | 🔴 **Opus** | Architectural decision with trade-offs, long-term impact |
- | "plan microservices migration strategy" | 🔴 **Opus** | Complex architectural planning + strategic impact escalator |
-
- ### Business & Strategy
-
- | Task | Recommendation | Rationale |
- |---|---|---|
- | "summarize this meeting transcript" | 🟢 **Haiku** | Simple text transformation, <2K words |
- | "extract action items from notes" | 🟢 **Haiku** | Data extraction, no reasoning |
- | "write blog post about AI trends" | 🟡 **Sonnet** | Creative writing, moderate reasoning |
- | "draft sales proposal for enterprise client" | 🟡 **Sonnet** | Persuasive writing, moderate reasoning |
- | "analyze competitor pricing strategy" | 🟡 **Sonnet** | Research/analysis, single framework |
- | "plan market entry strategy for Europe" | 🔴 **Opus** | Strategic impact + cross-functional + ambiguity escalators |
- | "design organizational restructuring plan" | 🔴 **Opus** | Political sensitivity + multiple stakeholders + strategic impact |
- | "M&A due diligence analysis" | 🔴 **Opus** | Strategic stakes + cross-functional synthesis required |
- | "crisis communication plan for data breach" | 🔴 **Opus** | Political sensitivity + stakes + multiple stakeholders |
-
- ### Creative & Analysis
-
- | Task | Recommendation | Rationale |
- |---|---|---|
- | "translate paragraph to French" | 🟢 **Haiku** | Simple language transform, no reasoning |
- | "brainstorm product names (single session)" | 🟡 **Sonnet** | Creative generation, moderate reasoning |
- | "brainstorm with SCAMPER + trade-off analysis" | 🔴 **Opus** | Multi-framework escalator (SCAMPER + weighted scoring) |
- | "retrospect: analyze collaboration patterns" | 🔴 **Opus** | Pattern detection + bias identification escalators |
- | "identify blindspots in strategy" | 🔴 **Opus** | Bias identification + ethical reasoning escalators |
- | "plan 3-day conference with speakers" | 🔴 **Opus** | Complex scheduling + multiple stakeholders + constraints |
-
- ### Commands, Skills, Agents
-
- | Task | Recommendation | Rationale |
- |---|---|---|
- | "command: convert EPUB to markdown" | 🟢 **Haiku** | Simple workflow, minimal reasoning |
- | "command: save session context" | 🟡 **Sonnet** | Context management, serialization logic |
- | "command: brainstorm with research + SCAMPER" | 🔴 **Opus** | Multi-framework escalator + strategic analysis |
- | "command: retrospect domain learnings" | 🔴 **Opus** | Pattern detection across sessions + bias identification |
- | "skill: format code with prettier" | 🟢 **Haiku** | Simple deterministic task |
- | "skill: standard workflow implementation" | 🟡 **Sonnet** | Standard workflow, moderate reasoning |
- | "agent: explore codebase architecture" | 🔴 **Opus** | Complex exploration + architectural synthesis |
-
- ## Philosophy
-
- - **Right-size, don't default up** — the cheapest model that meets quality requirements is the correct choice; upgrading is easy, right-sizing takes discipline.
- - **Task type over task size** — model selection depends on reasoning complexity, not the volume of text or files involved.
- - **Tier aliases over model names** — use fast/balanced/reasoning tiers; specific model names change; tier semantics persist.
- - **Escalate explicitly** — if a lower tier fails, escalate with a documented reason rather than defaulting to the top tier always.
-
- ## When to Use
+ Set confidence to high when the task matches one tier clearly, medium when it sits between two tiers, and low when the task is too vague to classify. Ask one clarifying question instead of guessing when confidence is low.
- - When a user asks "which model should I use for this task?" before starting work
- - When selecting between multiple LLM tiers for an automated agent workflow or pipeline
- - When cost vs capability tradeoff needs to be explicit (e.g. batch jobs, production routing)
- - When an agent must self-assign a model for a sub-task without human input
- - When an existing workflow is over-spending on frontier models for simple tasks
+ ## Anti-Patterns
- ## When Not to Use
+ - **NEVER default to the most powerful model for every task.** Oversized models inflate cost with no quality gain on simple work. Match the tier to the reasoning demand. **Why:** Haiku handles classification and routing at a fraction of the cost.
+ - **NEVER classify on the task label alone.** Check the escalators first. **Why:** one missed signal, such as a security-sensitive refactor, turns a Sonnet task into an Opus task.
- - When the model is already fixed by infrastructure constraints (e.g. a provider only offers one model)
- - When the task has already been completed and model selection is moot
- - When the user is asking about non-Claude providers and needs a cross-vendor comparison tool
- - When fine-tuned or domain-specific models are the deciding factor, not tier
- - When the decision depends on real-time pricing data not available in this skill
+ ```text
+ # BAD: label only
+ "refactor the auth module" -> Sonnet (looks like single-file coding)
- ## Anti-Patterns
+ # GOOD: escalators checked
+ "refactor the auth module": Scope (3+ files) + Stakes (credentials) -> Opus
+ ```
- - **NEVER default to the most powerful model for every task** — Oversized models inflate costs without quality gain on simple tasks. **Why:** A haiku/flash-class model handles classification and routing at 10x lower cost.
- - **NEVER pick a model based on benchmark leaderboards alone** — Benchmark tasks often differ from production workloads. **Why:** Real task performance depends on prompt structure, context length, and domain specificity.
- - **NEVER hardcode model names in agent workflows** — Providers rename and deprecate models frequently. **Why:** Hardcoded names break silently on deprecation; use model tier aliases (fast/balanced/reasoning).
+ - **NEVER hardcode model identifiers in agent workflows.** **Why:** providers retire models, and a pinned identifier fails on the day it is retired. Use tier aliases and resolve them at runtime.
```yaml
- # BAD - pinned to a specific model id; breaks silently when the vendor retires it
+ # BAD: pinned identifiers that break on retirement
routing:
- summarizer: claude-3-haiku-20240307
+ summariser: claude-3-haiku-20240307
reviewer: claude-3-opus-20240229
- # GOOD - tier alias resolved to a current model id at runtime
+ # GOOD: tiers resolved to current models at runtime
routing:
- summarizer: fast # resolves to whichever model is the current fast tier
- reviewer: reasoning # resolves to whichever model is the current reasoning tier
- ```
-
- - **NEVER skip escalator checks for ambiguous tasks** — Underestimating complexity leads to poor output requiring costly reruns. **Why:** A single missed escalator (e.g. multi-stakeholder, security risk) can push a task from Sonnet to Opus quality requirements.
-
- ```text
- # BAD - classifies on task label alone, ignores escalator signals
- Task: "refactor the auth module"
- -> Sonnet (looks like "single-file coding")
-
- # GOOD - checks escalators before committing to a tier
- Task: "refactor the auth module"
- Escalators checked: touches 3+ files (Scope) + handles credentials (Stakes)
- -> Opus (two escalators fired; Sonnet would under-resource this)
+ summariser: fast
+ reviewer: reasoning
```
- - **NEVER conflate speed preference with model tier** — Choosing Haiku solely for latency on a reasoning-heavy task produces wrong answers. **Why:** Speed and capability are separate dimensions; use the decision matrix first, then consider latency constraints.
+ - **NEVER pick a model from benchmark leaderboards alone.** Test the shortlisted tier on a sample of the real workload. **Why:** benchmark tasks differ from your workload, so real performance depends on prompt structure, context length and domain.
+ - **NEVER choose Haiku for production-critical work to save money.** Apply the stakes escalator instead. **Why:** this is the false economy pitfall, because one outage or rework cycle costs far more than the saving.
+ - **NEVER treat speed as a tier.** **Why:** a fast model on a reasoning-heavy task returns wrong answers faster. Settle the tier first, then apply latency.
+ - **NEVER override an explicit user model choice.** Recommend only when no model is named. **Why:** the user often holds constraints, such as budget or latency, that the task text does not show.
+ - **NEVER quote prices or speed multipliers as fact.** **Why:** they change between releases. Describe cost and speed as relative ranks. Send readers to current vendor pricing for exact figures.
- ## Usage Examples
+ ## Worked Examples
- **Selecting a model for a code review task:**
- ```bash
- # Task: review 200-line TypeScript file for bugs
- # Tier: balanced (Sonnet-class) — reasoning needed but not frontier
- # Escalators: none (single file, no production risk flagged)
- # Output: model alias + rationale
- # -> Recommendation: Sonnet — single-file code review, moderate reasoning required
+ ```text
+ Task: "summarise 5 meeting notes into bullets"
+ Matrix: Haiku. Escalators: none (under 2K words, no trade-offs).
+ Result: 🟢 Haiku, because it is plain text transformation.
```
- **Routing a summarization request:**
- ```bash
- # Task: summarize 5 meeting notes into bullet points
- # Tier: fast (Haiku-class) — no complex reasoning needed
- # Escalators: none (<2K words, no stakeholder trade-offs)
- # -> Recommendation: Haiku — simple text transformation, no judgment required
+ ```text
+ Task: "fix a typo in the production payment config"
+ Matrix: Haiku. Escalators: Stakes (production, payments) -> one tier up.
+ Result: 🟡 Sonnet. A typo alone is Haiku work; the stakes decide this one.
```
- **Classifying a strategic planning task:**
- ```bash
- # Task: design a market entry strategy for a new region
- # Tier: reasoning (Opus-class)
- # Escalators: strategic impact + cross-functional synthesis + ambiguity
- # -> Recommendation: Opus — multiple escalators detected (strategic impact, ambiguity, cross-functional)
+ ```text
+ Task: "plan market entry for a new region"
+ Matrix: Sonnet. Escalators: Irreversibility, Synthesis, Ambiguity -> one tier up, capped at Opus.
+ Result: 🔴 Opus. Three signals fired but the move is one tier, not three.
```
+ More cases are in [worked examples](references/examples.md).
+
## References
- - [Reference](references/reference.md) — extended decision matrix by file type and domain, cost/latency tradeoffs, edge cases, hybrid task patterns, and common mistakes
+ - [Decision matrix](references/decision-matrix.md): base tiers by technical, business, creative and command or agent task
+ - [Escalators](references/escalators.md): signal definitions, borderline readings and what does not count
+ - [Worked examples](references/examples.md): classified tasks by domain with the deciding signal
+ - [Reference](references/reference.md): model characteristics, file-type and domain matrices, cost and latency trade-offs, hybrid patterns and common mistakes
+