Complexity-based task routing for optimal model selection and cost efficiency. Use when deciding which model tier to use, analyzing task complexity, optimizing API costs, or implementing tiered routing. Trigger keywords - "routing", "complexity", "model selection", "tier", "cost optimization", "haiku", "sonnet", "opus", "task analysis".
Complexity-based task routing for optimal model selection and cost efficiency. Use when deciding which model tier to use, analyzing task complexity, optimizing API costs, or implementing tiered routing. Trigger keywords - "routing", "complexity", "model selection", "tier", "cost optimization", "haiku", "sonnet", "opus", "task analysis".
Version: 1.0.0
Purpose: Intelligent task routing to optimal model tiers for cost efficiency and performance
Production Ready
Status:
Overview
Task complexity routing is the practice of matching tasks to appropriate model tiers based on complexity, urgency, and resource requirements. Instead of using expensive premium models for all tasks, routing directs simple tasks to fast/cheap models and reserves expensive models for complex work.
Patterns: Single regex, exact string replacement, file path operations
Cost: $0
Speed: Instant (< 0.1s)
Examples:
✓ "Find all .tsx files in src/"
✓ "Search for 'TODO' comments"
✓ "Format code with prettier"
✓ "Rename Button.js to Button.tsx"
✓ "Show git status"
✓ "Replace 'oldName' with 'newName' in file.ts"
Implementation:
Task: "Find all TypeScript files"
→ Use Glob tool: *.ts
→ No LLM needed
Task: "Search for API endpoints"
→ Use Grep tool: "app\.(get|post|put|delete)"
→ No LLM needed
Task: "Format all code"
→ Use Bash: bun run format
→ No LLM needed
Complexity: No architectural decisions, clear solution
Cost: ~$0.0004 per task (1000 tokens)
Speed: Fast (1-3s response time)
Examples:
✓ "Add JSDoc comment to calculateTotal function"
✓ "Fix typo in error message"
✓ "Rename getUserData to fetchUserData"
✓ "Update README with new installation steps"
✓ "Add missing import statement"
✓ "Write unit test for add(a, b) function"
✓ "Implement user profile page with React"
✓ "Create REST API endpoint for /users/:id"
✓ "Refactor authentication logic into AuthService"
✓ "Fix pagination bug in user list"
✓ "Write integration tests for payment flow"
✓ "Add error handling to API calls"
This is the Default Tier:
When in doubt, use Sonnet. It handles 70% of standard development tasks well.
✓ "Design microservices architecture for e-commerce platform"
✓ "Audit authentication system for security vulnerabilities"
✓ "Debug intermittent race condition in WebSocket handler"
✓ "Optimize algorithm for 1M+ record processing"
✓ "Review entire codebase for architectural issues"
✓ "Design database schema for multi-tenant SaaS"
When to Escalate to Opus:
Task starts in Sonnet, but:
- Task fails after 2 attempts → Escalate to Opus
- User explicitly says "this is complex" → Escalate to Opus
- Implementation reveals architectural issues → Escalate to Opus
- Performance/security concerns discovered → Escalate to Opus
Complexity Detection Heuristics
Keyword-Based Routing
Scoring Algorithm:
Step 1: Extract keywords from user request
Step 2: Score each keyword:
Tier 0 indicators: +0 points
- find, search, list, show, format, rename, move, copy, grep
Tier 1 indicators: +1 point
- simple, basic, small, quick, minor, add, fix, update, comment
Tier 2 indicators: +2 points
- implement, create, build, refactor, integrate, develop, feature
Tier 3 indicators: +3 points
- architect, design, audit, complex, system-wide, critical, optimize
Step 3: Calculate total score
Score 0: Use native tools (Tier 0)
Score 1-2: Use Haiku (Tier 1)
Score 3-5: Use Sonnet (Tier 2)
Score 6+: Use Opus (Tier 3)
Step 4: Apply context modifiers (next section)
User explicitly requests tier:
"Use Haiku to add comment"
→ Override routing, use Haiku (Tier 1)
"Use Opus to review this"
→ Override routing, use Opus (Tier 3)
Priority: User override > Routing algorithm
Fallback Strategy:
When routing is uncertain:
- Score is borderline (e.g., 2.5 between tiers)
- Mixed signals (simple keywords, complex context)
- No clear indicators
Action: Default to Sonnet (Tier 2)
- Safe choice for most tasks
- Not too expensive ($0.003 vs $0.015)
- Good quality for standard work
- Can escalate to Opus if needed
Emergency Escalation:
Task fails at current tier:
Attempt 1: Use routed tier (e.g., Haiku)
Attempt 2: Same tier, different approach
Attempt 3: Escalate +1 tier (e.g., Sonnet)
Attempt 4: Escalate to Opus (highest tier)
Example:
Task: "Fix subtle bug" → Haiku (Tier 1)
Result: Fails to identify root cause
→ Retry with Haiku (different prompt)
Result: Still fails
→ Escalate to Sonnet (Tier 2)
Result: Identifies bug, fixes it ✓
Cost Optimization Patterns
Cost-Benefit Analysis
When to Upgrade Tier:
Upgrade from Tier 1 (Haiku) to Tier 2 (Sonnet):
Cost increase: $0.002 (0.5x more)
Upgrade when:
- Task failed 2+ times at Tier 1
- Task requires multi-file context
- Risk of incorrect solution is high
- Time spent debugging > cost savings
Upgrade from Tier 2 (Sonnet) to Tier 3 (Opus):
Cost increase: $0.012 (5x more)
Upgrade when:
- Task has critical security/performance implications
- Architecture decisions needed
- Task failed 2+ times at Tier 2
- Complex reasoning required (trade-offs, edge cases)
When to Downgrade Tier:
Downgrade from Tier 2 (Sonnet) to Tier 1 (Haiku):
Cost savings: $0.002 (50% reduction)
Downgrade when:
- Subtask is simpler than parent task
- Clear, straightforward solution exists
- Single file, < 50 lines changed
- No architectural decisions needed
Example:
Main task: "Implement user profile" → Sonnet (Tier 2)
Subtask 1: "Add JSDoc to ProfileCard" → Haiku (Tier 1)
Subtask 2: "Write unit test for formatDate" → Haiku (Tier 1)
Subtask 3: "Integrate with API" → Sonnet (Tier 2)
Use Case: Code review with budget constraints
Step 1: Fast pre-review (Tier 1 - Haiku)
Task: "Check for obvious issues: syntax, imports, formatting"
Model: Haiku (fast, cheap)
Output: Found 3 obvious issues (missing import, typo, formatting)
Step 2: Fix obvious issues
Developer fixes issues found by Haiku
Step 3: Deep review (Tier 3 - Opus)
Task: "Security audit and architectural review"
Model: Opus (complex, critical)
Output: Found 2 security issues
Cost:
Without tiering: Opus review all issues = $0.025
With tiering: Haiku pre-review ($0.001) + Opus deep review ($0.015) = $0.016
Savings: 36%
Benefit: Haiku caught simple issues fast, Opus focused on complex issues
Routing + Quality Gates
Pattern: Escalation on Failure
Workflow: Test-driven development with escalation
Iteration 1: Run tests (Tier 2 - Sonnet)
Task: "Analyze test failures and fix"
Model: Sonnet
Result: Fixed 8/10 failures
Cost: $0.003
Iteration 2: Re-run tests (Tier 2 - Sonnet)
Task: "Fix remaining 2 failures"
Model: Sonnet
Result: Still failing (complex race condition)
Cost: $0.003
Iteration 3: Escalate to Opus (Tier 3)
Task: "Debug complex race condition"
Model: Opus (escalated due to failure)
Result: Identified root cause, fixed ✓
Cost: $0.015
Total Cost: $0.021
Without escalation: 3 × Opus = $0.045 (214% more expensive)
With escalation: Try cheaper first, upgrade only when needed
Routing + Proxy Mode
Pattern: External Model Routing
Use Case: Use external fast models for simple tasks
Task: "Add comments to functions"
Complexity: Simple (Tier 1)
Option 1: Claude Haiku 4.5 (OpenRouter)
Cost: $0.004
Speed: 2s
Option 2: DeepSeek Coder (OpenRouter)
Cost: $0.001 (75% cheaper than Haiku)
Speed: 3s
Option 3: Grok Code Fast (OpenRouter)
Cost: $0.002 (50% cheaper than Haiku)
Speed: 1s (fastest)
Routing Decision:
If speed priority: Use Grok Code Fast
If cost priority: Use DeepSeek Coder
If balance: Use Claude Haiku (best quality/cost/speed)
Implementation:
Task: task-executor
Model: grok-code-fast-1
Prompt: "Add JSDoc comments to all functions in UserService.ts"
claudish: x-ai/grok-code-fast-1
Best Practices
Do:
✅ Use native tools (Tier 0) for file operations and searches (instant, free)
✅ Start with cheaper tiers and escalate only when needed
✅ Track costs per task for optimization insights
✅ Set max cost budgets per workflow (e.g., $0.10 per feature)
✅ Split complex tasks into simpler subtasks (route each separately)
✅ Use Haiku for documentation, comments, simple tests
✅ Use Sonnet as default for standard development
✅ Reserve Opus for architecture, security, complex debugging
✅ Escalate tier after 2 failures at current tier
✅ Document routing decisions for team alignment
Don't:
❌ Use Opus for every task (waste money, slower)
❌ Use Haiku for complex tasks (will fail, waste time)
❌ Ignore user context (security/critical tasks need higher tier)
❌ Skip cost tracking (can't optimize what you don't measure)
❌ Over-optimize for cost (quality matters more than pennies)
❌ Use LLM when native tools work (search, format, rename)
❌ Downgrade tier for critical tasks (security, production bugs)
❌ Route without fallback strategy (always have Sonnet default)
Example 3: Cost Comparison Showing Savings from Routing
Scenario: Weekly development for small team (3 developers)
Task Distribution:
Week 1: 150 total tasks
Task Breakdown (with smart routing):
Tier 0 (Native): 50 tasks (file ops, searches, formatting)
Cost: $0
Time: 50 × 1s = 50s
Tier 1 (Haiku): 45 tasks (comments, docs, simple fixes)
Cost: 45 × $0.004 = $0.18
Time: 45 × 2s = 90s
Tier 2 (Sonnet): 45 tasks (features, refactors, integrations)
Cost: 45 × $0.030 = $1.35
Time: 45 × 8s = 360s
Tier 3 (Opus): 10 tasks (architecture, security, complex bugs)
Cost: 10 × $0.150 = $1.50
Time: 10 × 25s = 250s
Total with Routing:
Cost: $3.03
Time: 750s (12.5 min)
Tasks completed: 150
Cost Comparison:
Strategy 1: All Opus (premium everywhere)
150 tasks × $0.150 = $22.50
Difference: +$19.47 (7.4× more expensive)
Strategy 2: All Sonnet (standard everywhere)
150 tasks × $0.030 = $4.50
Difference: +$1.47 (1.5× more expensive)
Strategy 3: Random 50/50 Haiku/Sonnet (no routing logic)
75 × $0.004 + 75 × $0.030 = $2.55
Quality issues: 15 tasks failed (Haiku used for complex)
Re-work: 15 × $0.030 = $0.45
Total: $3.00 (similar cost, but failures and delays)
Strategy 4: Smart Routing (this approach)
Cost: $3.03
Quality: High (each task matched to appropriate tier)
Speed: Optimal (fast models for simple, premium for complex)
Annual Savings (3 developers × 52 weeks):
vs All Opus: 52 × $19.47 = $1,012.44
vs All Sonnet: 52 × $1.47 = $76.44
vs Random: 52 × $0.45 (re-work) = $23.40
ROI:
Save $1,000+ annually vs premium-everywhere approach
Save $76 annually vs standard-everywhere approach
Better quality than random routing
Troubleshooting
Problem: Task routed to Haiku, but failed
Cause: Task more complex than keywords suggested
Solution: Escalate to next tier (Sonnet) and retry
❌ Wrong:
Task fails with Haiku
→ Give up or ask user for help
✅ Correct:
Task fails with Haiku (Attempt 1)
→ Retry with different prompt (Attempt 2)
→ Still fails? Escalate to Sonnet (Attempt 3)
→ Fixed ✓
Problem: Too many tasks routed to Opus (high costs)
Cause: Overly aggressive routing, not splitting tasks
Solution: Break complex tasks into simpler subtasks
