task-complexity-router

What this skill does

# Task Complexity Router

**Version:** 1.0.0
**Purpose:** Intelligent task routing to optimal model tiers for cost efficiency and performance
**Status:** Production Ready

## 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.

This skill provides battle-tested patterns for:
- **4-tier routing system** (Native Tools → Haiku → Sonnet → Opus)
- **Complexity detection heuristics** (keyword-based + context-based)
- **Cost optimization strategies** (save 60-90% on API costs)
- **Dynamic tier escalation** (upgrade when task stalls or fails)
- **Routing integration** (works with multi-agent-coordination, quality-gates, proxy-mode)

Well-designed routing can **reduce AI costs by 60-90%** while maintaining quality, since 70% of tasks can be handled by faster, cheaper models.

## Why Task Routing Matters

### Cost Comparison (per 1M tokens)

| Model Tier | Model Example | Cost (Input/Output) | Speed | Use Case |
|------------|---------------|---------------------|-------|----------|
| **Tier 0** | Native Tools | $0 | Instant | File operations, searches, formatting |
| **Tier 1** | Claude Haiku 4.5 | $0.80 / $4.00 | Fast | Simple edits, docs, straightforward tasks |
| **Tier 2** | Claude Sonnet 4.5 | $3.00 / $15.00 | Moderate | Standard dev, multi-file changes |
| **Tier 3** | Claude Opus 4.5 | $15.00 / $75.00 | Slower | Architecture, complex debugging, audits |

**Example Cost Savings:**

```
Scenario: 100 tasks per day (mix of simple and complex)

Without Routing (all Sonnet):
  100 tasks × 1000 tokens avg × $0.015 = $1.50/day
  Annual: $547.50

With Smart Routing:
  50 tasks (native tools) × $0 = $0
  30 tasks (Haiku) × $0.004 = $0.12
  15 tasks (Sonnet) × $0.015 = $0.22
  5 tasks (Opus) × $0.075 = $0.37
  Total: $0.71/day
  Annual: $259.15

Savings: $288.35/year (52% reduction) for single developer
```

### Performance Benefits

Beyond cost savings, routing improves:
- **Speed:** Fast models return results in 1-2s vs 10-15s for premium
- **Throughput:** Process 5x more simple tasks in parallel
- **Resource efficiency:** Save premium model quota for critical tasks
- **User experience:** Instant results for simple operations

## The 4-Tier Routing System

### Tier 0: Native Tools (No LLM)

**When to Use:**
- File operations (search, rename, move, copy)
- Content search (grep, regex)
- Code formatting (prettier, black, go fmt)
- Git operations (status, log, diff)
- Single-file edits with clear pattern

**Indicators:**
- Keywords: "find", "search", "format", "rename", "list", "show"
- 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
```

---

### Tier 1: Fast Model (Haiku)

**When to Use:**
- Simple code changes (add comment, fix typo, rename variable)
- Documentation updates (README, JSDoc, inline comments)
- Straightforward bug fixes (missing import, syntax error)
- Code explanation (what does this function do?)
- Simple test writing (unit test for pure function)

**Indicators:**
- Keywords: "simple", "basic", "small", "quick", "minor", "add", "fix", "update"
- Scope: Single file, < 50 lines changed
- 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"
```

**Anti-Patterns (Don't Use Haiku For):**
```
✗ "Design authentication system" (needs Opus)
✗ "Refactor entire codebase" (needs Sonnet + context)
✗ "Debug complex race condition" (needs Opus)
✗ "Architect database schema" (needs Opus)
```

---

### Tier 2: Standard Model (Sonnet)

**When to Use:**
- Standard feature implementation (new component, API endpoint)
- Multi-file refactoring (rename class, extract service)
- Integration tasks (connect frontend to backend)
- Moderate bug fixes (logic errors, edge cases)
- Test suites (integration tests, E2E tests)

**Indicators:**
- Keywords: "implement", "create", "build", "refactor", "integrate", "develop"
- Scope: 2-10 files, 50-500 lines changed
- Complexity: Requires understanding context, moderate problem-solving

**Cost:** ~$0.003 per task (1000 tokens)
**Speed:** Moderate (5-10s response time)

**Examples:**
```
✓ "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.

---

### Tier 3: Premium Model (Opus)

**When to Use:**
- Architecture decisions (system design, database schema)
- Complex debugging (race conditions, memory leaks, security issues)
- Security audits (vulnerability analysis, threat modeling)
- Performance optimization (algorithm complexity, bottleneck analysis)
- Code review (deep analysis, architectural feedback)
- Critical bug fixes (production outages, data corruption)

**Indicators:**
- Keywords: "architect", "design", "audit", "complex", "system-wide", "critical", "optimize"
- Scope: System-wide impact, 10+ files, architectural changes
- Complexity: Requires deep reasoning, multiple trade-offs

**Cost:** ~$0.015 per task (1000 tokens)
**Speed:** Slower (15-30s response time)

**Examples:**
```
✓ "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)
```

**Example Scoring:**

```
Request: "Add simple comment to function"
Keywords: "add" (+1), "simple" (+1), "comment" (+1)
Score: 3 → Sonnet (Tier 2)
Context Modifier: Single file → -1 → Score 2 → Haiku (Tier 1)

Request: "Implement user authentication"
Keywords: "implement" (+2), "authentication" (+3)
Score: 5 →