Reasoning Controls

Reasoning Controls

Overview

Control reasoning depth and cost trade-offs using consistent settings and metrics.

When to Use

• Adjusting reasoning depth or thinking mode
• Setting budget limits for cost or latency
• Reporting reasoning metrics

Avoid when:

• The task doesn’t require explicit reasoning controls

Quick Reference

Workflow

1. Determine the control goal (depth, budget, metrics). 2. Load the matching reference. 3. Apply the control with the appropriate parameters. 4. Report settings and effects.

Output

• Updated reasoning settings
• Metrics or confirmation output

Common Mistakes

• Over-allocating budget for simple tasks
• Changing depth without explaining trade-offs

Reference: adjust

/reasoning:adjust - Dynamic Reasoning Depth Control

Personas (Thinking Modes)

• performance-engineer: Depth optimization, runtime efficiency, complexity assessment
• architect: Task complexity analysis, appropriate reasoning level, quality requirements
• cost-optimizer: Budget awareness, depth-cost trade-offs, efficiency recommendations

Delegation Protocol

This command does NOT delegate - Reasoning adjustment is configuration change.

Why no delegation:

• ❌ Fast configuration update (<1 second)
• ❌ Simple parameter adjustment
• ❌ Direct MCP server activation/deactivation
• ❌ No complex execution required

All work done directly:

• Assess current reasoning depth
• Validate requested adjustment
• Update configuration parameters
• Reconfigure MCP server activation

Note: Personas guide adjustment decisions (performance for efficiency, architect for appropriateness, optimizer for cost).

Tool Coordination

• Direct configuration: Reasoning depth adjustment (direct)
• MCP reconfiguration: Server activation based on depth (direct)
• No delegation needed: Simple configuration change

Triggers

• Need to escalate or reduce reasoning depth during complex task execution
• Initial analysis insufficient or overly verbose for current subtask
• Performance optimization during long-running operations
• Runtime adaptation based on emerging task complexity

Usage

/reasoning:adjust [low|medium|high|ultra] [--scope current|remaining]

Behavioral Flow

1. Assess: Evaluate current reasoning depth and task context 2. Validate: Confirm depth change is appropriate for operation type 3. Adjust: Reconfigure analysis parameters and MCP server activation 4. Apply: Execute remaining work with new depth configuration 5. Track: Monitor effectiveness and suggest further adjustments if needed

Key behaviors:

• Runtime depth switching without restarting task execution
• Intelligent scope control (current subtask vs remaining work)
• MCP server activation/deactivation based on depth changes
• Token budget reallocation for optimal resource utilization

Reasoning Depth Levels

Low (~2K tokens)

• Use case: Simple operations, quick iterations, prototyping
• MCP servers: None (native tools only)
• Analysis style: Direct solutions, minimal exploration
• Token budget: ~2,000 tokens per analysis phase

Medium (~4K tokens)

• Use case: Standard development tasks, moderate complexity
• MCP servers: Sequential (structured reasoning)
• Analysis style: Systematic exploration, hypothesis testing
• Token budget: ~4,000 tokens per analysis phase
• Equivalent: --think flag

High (~10K tokens)

• Use case: Architectural decisions, system-wide dependencies
• MCP servers: Sequential + Context7 (official patterns)
• Analysis style: Deep exploration, trade-off analysis, pattern research
• Token budget: ~10,000 tokens per analysis phase
• Equivalent: --think-hard flag

Ultra (~32K tokens)

• Use case: Critical redesigns, legacy modernization, complex debugging
• MCP servers: All available (Sequential, Context7, Codanna, etc.)
• Analysis style: Maximum depth, exhaustive exploration, meta-analysis
• Token budget: ~32,000 tokens per analysis phase
• Equivalent: --ultrathink flag
• Auto-enables: --introspect transparency markers

Scope Control

--scope current

• Apply depth change to current subtask only
• Revert to previous depth after completion
• Use for: Isolated complexity spikes

--scope remaining

• Apply depth change to all remaining work (default)
• Persist through task hierarchy
• Use for: Sustained complexity adjustment

Tool Coordination

• TodoWrite: Update task tracking with depth change notifications
• Read/Grep: Adjust file analysis thoroughness based on depth
• MCP Servers: Activate/deactivate based on depth level

Key Patterns

• Escalation: Low → Medium → High → Ultra (complexity increases)
• De-escalation: Ultra → High → Medium → Low (optimization/iteration)
• Targeted: Maintain base depth, spike for specific subtasks
• Adaptive: Monitor effectiveness, suggest further adjustments

Examples

Escalate for Complex Subtask

/reasoning:adjust ultra --scope current
# Escalate to maximum depth for current complex subtask only
# Reverts to previous depth after completion

Optimize Long-Running Analysis

/reasoning:adjust medium --scope remaining
# Reduce depth for faster iteration in remaining work
# Useful when initial deep analysis provided sufficient context

Spike for Architecture Decision

/reasoning:adjust high --scope current
# Deep analysis for architectural decision point
# Return to standard depth for implementation

Maximum Depth Investigation

/reasoning:adjust ultra --scope remaining
# Full depth for complex debugging or system redesign
# Enables all MCP servers and introspection markers

Boundaries

Will:

• Dynamically adjust reasoning depth during task execution
• Reconfigure MCP server activation and token budgets
• Provide scope control for targeted vs sustained adjustments
• Suggest optimal depth based on task characteristics

Will Not:

• Override explicit user depth preferences without confirmation
• Change depth mid-analysis (waits for subtask boundaries)
• Disable critical safety validations regardless of depth
• Adjust depth for operations requiring specific configurations

Reference: budget

/reasoning:budget - Thinking Budget Control

Personas (Thinking Modes)

• cost-optimizer: Budget allocation, cost-benefit analysis, resource efficiency
• performance-engineer: Quality-cost trade-offs, reasoning effectiveness measurement
• architect: Task complexity assessment, appropriate budget sizing

Delegation Protocol

This command does NOT delegate - Budget control is configuration setting.

Why no delegation:

• ❌ Instant configuration change
• ❌ Simple token budget setting
• ❌ Direct monitoring setup
• ❌ No execution required (just configuration)

All work done directly:

• Assess task complexity
• Set thinking token budget
• Enable usage monitoring if requested
• Track and report token consumption

Note: Personas guide budget decisions (optimizer for efficiency, performance for quality, architect for complexity).

Tool Coordination

• Direct configuration: Token budget setting (direct)
• Usage monitoring: Token tracking (direct if --show-usage)
• No delegation needed: Pure configuration command

Triggers

• Need to control reasoning depth and cost trade-offs
• Complex problems requiring extended thinking time
• Budget-conscious operations with quality requirements
• Performance optimization requiring variable reasoning depth

Usage

/reasoning:budget [4000|10000|32000|128000] [--auto-adjust] [--show-usage]

Behavioral Flow

1. Assess: Evaluate task complexity and budget requirements 2. Configure: Set internal thinking token budget for analysis 3. Monitor: Track token usage during reasoning process 4. Optimize: Suggest budget adjustments based on effectiveness 5. Report: Provide usage metrics and recommendations

Key behaviors:

• Fine-grained control over internal reasoning depth
• Cost optimization through explicit budget management
• Quality/cost trade-off visibility
• Automatic budget adjustment based on task complexity

Budget Levels

Standard (4,000 tokens)

• Use case: Routine development tasks, quick analysis
• MCP servers: Sequential (optional)
• Thinking depth: Systematic exploration with basic hypothesis testing
• Cost: ~$0.012 per request (input)
• Equivalent: --think / /reasoning:adjust medium
• Best for: Code reviews, simple refactoring, standard debugging

Deep (10,000 tokens)

• Use case: Architectural decisions, complex refactoring
• MCP servers: Sequential + Context7
• Thinking depth: Deep exploration with trade-off analysis
• Cost: ~$0.030 per request (input)
• Equivalent: --think-hard / /reasoning:adjust high
• Best for: System design, dependency analysis, performance optimization

Maximum (32,000 tokens)

• Use case: Critical system redesign, legacy modernization
• MCP servers: All available (Sequential, Context7, Codanna)
• Thinking depth: Exhaustive exploration with meta-analysis
• Cost: ~$0.096 per request (input)
• Equivalent: --ultrathink / /reasoning:adjust ultra
• Best for: Complex debugging, architectural transformation, security audits

Extended (128,000 tokens) 🆕

• Use case: Extreme complexity requiring extended thinking time
• MCP servers: All available + skill composition
• Thinking depth: Maximum possible reasoning with exhaustive analysis
• Cost: ~$0.384 per request (input)
• Equivalent: Claude 3.7 Extended Thinking Mode
• Best for:
• Multi-system integration challenges
• Complex mathematical proofs or physics problems
• Enterprise-scale architectural decisions
• Security vulnerability chains with multiple attack vectors
• Legacy system modernization with extensive dependencies

Budget Control Options

--auto-adjust

Automatically adjust budget based on task complexity signals:

• Escalation triggers: Circular dependencies, >100 files, >10 service boundaries
• De-escalation triggers: Simple patterns detected, confidence >0.9
• Behavior: Starts at requested budget, adjusts up/down as needed
• Max escalation: One level up (e.g., 10K → 32K, not 10K → 128K)

--show-usage

Display real-time thinking budget consumption:

• Current tokens used vs allocated
• Estimated cost for current operation
• Budget efficiency score (quality per token)
• Recommendation for future similar tasks

Cost Optimization Strategies

Budget Selection Guide

Budget Too Low Indicators:

• Multiple solution attempts (>3) failing
• Confidence scores consistently <0.6
• Request for /reasoning:adjust escalation
• Circular reasoning or repeated analysis

Budget Too High Indicators:

• Task completed using <50% of allocated budget
• Solution found in first attempt with high confidence
• Minimal MCP server activation
• Simple, direct solution path

Recommended Budgets by Task Type

Code Analysis:

• Quick scan: 4K
• Comprehensive: 10K
• Security audit: 32K
• Multi-system: 128K

System Design:

• Component design: 10K
• Service architecture: 32K
• Enterprise platform: 128K

Debugging:

• Simple bugs: 4K
• Complex bugs: 10K
• System-wide issues: 32K
• Production incidents: 128K

Refactoring:

• Function-level: 4K
• Module-level: 10K
• System-wide: 32K
• Legacy modernization: 128K

Integration with Other Reasoning Controls

Combined with /reasoning:adjust

# Set budget, then adjust depth mid-task
/reasoning:budget 32000
# ... task begins ...
/reasoning:adjust high --scope current
# Respects 32K budget but adjusts MCP activation

Combined with --summary

# Extended thinking with brief output
--thinking-budget 128000 --summary brief
# Maximum reasoning, minimal output verbosity

Combined with --reasoning-profile

# Extended security analysis
/analyze:code --thinking-budget 128000 --reasoning-profile security
# Maximum depth + domain specialization

Tool Coordination

• TodoWrite: Budget monitoring and task tracking
• Read/Grep: Scope analysis for budget estimation
• MCP Servers: Activated based on budget level
• Skill System: Extended mode enables full skill composition

Key Patterns

• Budget Ladder: 4K → 10K → 32K → 128K (progressive escalation)
• Cost Awareness: Show cost implications before extended thinking
• Quality Metrics: Track reasoning effectiveness per budget level
• Auto-Optimization: Learn optimal budgets for task patterns

Examples

Standard Development Task

/reasoning:budget 4000
# Set 4K budget for routine code review
# Cost-effective for simple analysis

Complex Architectural Decision

/reasoning:budget 32000 --auto-adjust
# Start with 32K, allow escalation to 128K if needed
# Balances cost with quality for uncertain complexity

Extended Thinking for Critical Issue

/reasoning:budget 128000 --show-usage
# Maximum depth for production incident investigation
# Monitor token usage and cost in real-time

Budget-Conscious Analysis

/reasoning:budget 10000
/analyze:code src/auth --reasoning-profile security
# Deep analysis within controlled budget
# Security profile + 10K tokens = thorough but not excessive

Boundaries

Will:

• Set explicit token budget for internal reasoning
• Monitor and report budget usage and efficiency
• Suggest optimal budgets based on task characteristics
• Enable extended thinking mode (128K) for extreme complexity

Will Not:

• Exceed budget without explicit --auto-adjust permission
• Charge for unused allocated budget (actual usage only)
• Guarantee quality solely based on budget (task-dependent)
• Replace manual depth adjustment (/reasoning:adjust)

Pricing Reference

Claude 3.7 Sonnet Pricing:

• Input: $3 per million tokens
• Output: $15 per million tokens

Extended Thinking Cost Examples:

• 4K thinking → ~$0.012 input
• 10K thinking → ~$0.030 input
• 32K thinking → ~$0.096 input
• 128K thinking → ~$0.384 input

Note: Output tokens charged separately based on actual response length. Extended thinking generates more output but also higher quality responses.

Cost Comparison:

• Claude 3.7 (128K): $0.384 per request
• OpenAI o1 (128K): $1.920 per request (5x more expensive)

Related Commands

• /reasoning:adjust - Runtime depth control (MCP activation)
• /reasoning:metrics - Track reasoning effectiveness
• /analyze:code --reasoning-profile - Domain-specific optimization

Reference: metrics

/reasoning:metrics - Reasoning Analytics Dashboard

Personas (Thinking Modes)

• data-analyst: Metrics interpretation, trend analysis, pattern recognition, statistical insights
• performance-engineer: Reasoning efficiency, execution time analysis, optimization recommendations
• cost-optimizer: Budget tracking, cost-benefit analysis, resource allocation guidance

Delegation Protocol

This command does NOT delegate - Metrics display is direct data presentation.

Why no delegation:

• ❌ Fast metrics retrieval and calculation
• ❌ Simple dashboard generation
• ❌ Direct data formatting and visualization
• ❌ No complex analysis required (just presentation)

All work done directly:

• Read metrics from command history/logs
• Calculate effectiveness scores
• Format dashboard output
• Generate recommendations based on patterns

Note: Personas guide metric interpretation (analyst for insights, performance for efficiency, optimizer for cost).

Tool Coordination

• Read: Command execution history and metrics data (direct)
• Direct calculation: Effectiveness scores and patterns (direct)
• Direct output: Dashboard generation (direct)
• No delegation needed: Simple data presentation

Triggers

• Need to understand reasoning effectiveness and costs
• Optimization of reasoning depth for specific task types
• Budget planning and cost analysis
• Performance tuning of reasoning strategies

Usage

/reasoning:metrics [--command <name>] [--timeframe 7d|30d|all] [--export json|markdown|csv]

Behavioral Flow

1. Collect: Gather reasoning metrics from command execution history 2. Analyze: Calculate effectiveness scores and patterns 3. Visualize: Generate dashboard with key metrics and trends 4. Recommend: Suggest optimal reasoning configurations 5. Export: Output metrics in requested format for analysis

Key behaviors:

• Track token usage by reasoning level and command
• Measure success rates and confidence scores
• Identify optimal depth/budget combinations
• Detect patterns in escalation triggers

Metrics Tracked

Token Usage Metrics

By Reasoning Depth:

• Low (2K): Actual usage, average, success rate
• Medium (4K): Actual usage, average, success rate
• High (10K): Actual usage, average, success rate
• Ultra (32K): Actual usage, average, success rate
• Extended (128K): Actual usage, average, success rate

By Budget Level:

• Allocated vs actual consumption
• Budget efficiency (quality per token)
• Underutilization percentage
• Overrun frequency

Quality Metrics

Success Indicators:

• Task completion rate by depth level
• Average confidence score per level
• First-attempt success rate
• Escalation frequency

Effectiveness Scores:

• Quality per token (QPT) ratio
• Solution efficiency index
• Reasoning depth optimization score

Cost Metrics

Spending Analysis:

• Total tokens consumed (input + output)
• Cost by reasoning level
• Cost per command type
• Monthly burn rate projection

ROI Analysis:

• Cost vs quality trade-offs
• Optimal budget recommendations
• Overspending detection

MCP Server Activation

Usage Patterns:

• Sequential: Activation frequency, avg tokens
• Context7: Activation frequency, pattern lookups
• Codanna: Activation frequency, symbol operations
• Combined activations per depth level

Dashboard Sections

1. Executive Summary

Reasoning Metrics Summary (Last 30 Days)
=========================================
Total Requests:           147
Total Tokens:             892,450
Total Cost:              $2.68
Avg Confidence:          0.87
Success Rate:            94.3%

Top Command:             /analyze:code (52 requests)
Most Effective Depth:    High (10K) - 96% success
Budget Efficiency:       87% (optimal usage)

2. Depth Distribution

Reasoning Depth Usage
=====================
Low (2K):       ▓▓▓▓▓▓▓▓░░░░░░░░  15% (22 requests)
Medium (4K):    ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  38% (56 requests)
High (10K):     ▓▓▓▓▓▓▓▓▓▓▓▓░░░░  32% (47 requests)
Ultra (32K):    ▓▓▓▓▓▓░░░░░░░░░░  12% (18 requests)
Extended (128K): ▓░░░░░░░░░░░░░░   3% (4 requests)

3. Cost Breakdown

Cost Analysis by Depth Level
=============================
Depth Level     Requests  Avg Tokens  Avg Cost   Total Cost
--------------------------------------------------------------
Low (2K)            22      1,847     $0.006     $0.12
Medium (4K)         56      3,921     $0.012     $0.67
High (10K)          47      9,234     $0.028     $1.31
Ultra (32K)         18     28,901     $0.087     $1.56
Extended (128K)      4    112,450     $0.337     $1.35
--------------------------------------------------------------
TOTAL              147     (avg 6,071)           $5.01

4. Success Rate Analysis

Success Rates by Depth
======================
Depth Level     Success   Failed   Escalated  Confidence
----------------------------------------------------------
Low (2K)         81.8%    13.6%      4.5%       0.78
Medium (4K)      92.9%     5.4%      1.8%       0.84
High (10K)       97.9%     2.1%      0.0%       0.91
Ultra (32K)     100.0%     0.0%      0.0%       0.95
Extended (128K) 100.0%     0.0%      0.0%       0.98

5. Command-Specific Metrics

Top Commands by Usage
=====================
Command              Requests  Avg Depth  Success  Avg Cost
------------------------------------------------------------
/analyze:code            52     High      96.2%    $0.031
/design:system           28     Ultra     100%     $0.094
/dev:implement           24     Medium    91.7%    $0.014
/reasoning:adjust        19     N/A       100%     $0.008
/orchestrate:spawn       14     High      92.9%    $0.029

6. Optimization Recommendations

Recommendations
===============
✓ /analyze:code: Currently optimal at High depth
  → 96% success, $0.031/request, rarely escalates

⚠ /dev:implement: Consider Medium→High for 8% tasks
  → 8% escalation rate, could start higher for complex tasks

⚠ Budget efficiency: 13% overallocation detected
  → 19 requests used <50% of allocated budget
  → Consider dynamic budgeting with --auto-adjust

✓ Extended thinking: High ROI on critical tasks
  → 100% success on 4 complex system designs
  → $1.35 total cost prevented 3+ days of rework

Export Formats

JSON Export

{
  "summary": {
    "total_requests": 147,
    "total_tokens": 892450,
    "total_cost_usd": 2.68,
    "avg_confidence": 0.87,
    "success_rate": 0.943
  },
  "by_depth": [
    {
      "level": "medium",
      "tokens": 4000,
      "requests": 56,
      "success_rate": 0.929,
      "avg_tokens_used": 3921,
      "avg_cost_usd": 0.012
    }
  ],
  "by_command": [...],
  "recommendations": [...]
}

Markdown Export

Full dashboard rendered as markdown table for documentation.

CSV Export

timestamp,command,depth,tokens_allocated,tokens_used,success,confidence,cost_usd
2025-10-18 14:32,analyze:code,high,10000,9234,true,0.92,0.028
2025-10-18 15:45,dev:implement,medium,4000,3821,true,0.88,0.011
...

Integration Points

With /reasoning:budget

# Get metrics to inform budget decisions
/reasoning:metrics --command analyze:code
# Shows: High (10K) optimal for analyze:code

# Set budget based on metrics
/reasoning:budget 10000

With /reasoning:adjust

# Track escalation patterns
/reasoning:metrics --export json
# Analyze: Which commands escalate most frequently?
# Adjust default depths accordingly

With --auto-escalate

# Metrics inform auto-escalation triggers
# High escalation rate → lower initial threshold
# Low escalation rate → higher initial threshold

Tool Coordination

• Read: Access metrics storage (JSON files)
• Grep: Pattern analysis in usage logs
• Bash: Generate visualizations with plotting tools
• Write: Export formatted metrics reports

Key Patterns

• Trend Analysis: Usage over time → budget optimization
• Command Profiling: Per-command optimal depth discovery
• Cost Optimization: Identify overallocation and underutilization
• Quality Tracking: Monitor confidence and success correlations

Examples

Overall Dashboard

/reasoning:metrics
# Show complete dashboard for last 30 days
# All metrics, recommendations, and trends

Command-Specific Analysis

/reasoning:metrics --command analyze:code
# Deep dive into analyze:code performance
# Optimal depth, success patterns, cost analysis

Export for Analysis

/reasoning:metrics --timeframe all --export json > metrics.json
# Export all historical data as JSON
# Use for custom analysis or visualization

Cost Planning

/reasoning:metrics --timeframe 30d --export csv
# 30-day cost analysis
# Budget planning and trend projection

Boundaries

Will:

• Track and analyze reasoning effectiveness metrics
• Provide cost analysis and optimization recommendations
• Export metrics in multiple formats for analysis
• Identify patterns and suggest improvements

Will Not:

• Automatically change reasoning settings (requires user action)
• Access or modify actual command execution
• Guarantee future performance based on historical metrics
• Store sensitive data from command outputs

Privacy & Data

Metrics Stored:

• Command name, timestamp, depth level
• Token usage, cost calculations
• Success/failure status, confidence scores
• MCP server activations

NOT Stored:

• Actual command inputs or outputs
• File contents or code being analyzed
• User identifiers or session data
• Sensitive configuration values

Storage Location:

• ~/.claude/.metrics/reasoning/
• JSON format, user-readable
• Can be deleted anytime without affecting functionality

Related Commands

• /reasoning:budget - Set thinking token budgets
• /reasoning:adjust - Runtime depth control
• /analyze:code --reasoning-profile - Domain optimization