task-complexity-router

# 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 → Sonnet (Tier 2) Request: "Design microservices architecture" Keywords: "design" (+3), "microservices" (+3), "architecture" (+3) Score: 9 → Opus (Tier 3) Request: "Find all TODO comments" Keywords: "find" (+0) Score: 0 → Native tools (Tier 0) ``` --- ### Context-Based Routing **File Count Modifier:** ``` Files affected (from user context or codebase analysis): 1 file → -1 tier (simpler) 2-5 files → No modifier 6-10 files → +0 tier (standard) 11+ files → +1 tier (complex) Example: Task: "Refactor authentication" (base Tier 2) Context: Affects 15 files Modifier: +1 tier → Opus (Tier 3) ``` **Code Complexity Modifier:** ``` Indicators of complexity (increase tier): - Async/await patterns (+1) - Error handling required (+1) - Database transactions (+1) - Security implications (+2) - Performance critical (+2) - System-wide impact (+2) Example: Task: "Fix login bug" (base Tier 2) Context: Security implications (+2) Final: Opus (Tier 3) ``` **User Context Modifier:** ``` User explicitly signals complexity: "This is simple" → -1 tier "This is complex" → +1 tier "Be careful" → +1 tier "Quick task" → -1 tier "Critical" → +1 tier Example: Task: "Update README" (base Tier 1) User: "Be careful, this affects onboarding" Modifier: +1 tier → Sonnet (Tier 2) ``` --- ### Override Patterns **User-Specified Model:** ``` 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) ``` --- ### Cost Tracking Integration **Track Costs Per Task:** ``` Task: "Implement user authentication" Model: Claude Sonnet 4.5 Tokens: 1500 input, 3000 output Cost: (1500 × $0.003 / 1000) + (3000 × $0.015 / 1000) = $0.0045 + $0.045 = $0.0495 Log to performance tracking: { "task": "Implement user authentication", "tier": 2, "model": "claude-sonnet-4-5", "tokens_in": 1500, "tokens_out": 3000, "cost": 0.0495, "duration_seconds": 8, "success": true } ``` **Aggregate Cost Metrics:** ``` Daily Cost Report: Tier 0 (Native): 45 tasks, $0.00 Tier 1 (Haiku): 30 tasks, $0.12 ($0.004 avg)