Debug

Tool: issue-debug Model: Efficient

Trigger & Intent

Triggered by: Explicit stack traces, failing CI/CD runs, or execution failures in implement.

Intent: Performs rigorous Root Cause Analysis (RCA) instead of blindly guessing fixes.

Resource Pooling

Capability profile: debugging — requires code_analysis, prefers cost_sensitive, fast_draft fallback.

Required Skills

Skill	Role
debug-assistant	Debugging guidance and hypothesis generation
debug-root-cause	Root cause identification
debug-reproduction	Minimal reproduction planning

Input Schema

{
  stackTrace?: string;
  observedBehavior: string;
  expectedBehavior: string;
}

Decisions & Throw-Backs

Attempts to write a minimal failing test case first. If the bug cannot be reproduced, throws back asking for more environment context. Once RCA is confirmed, routes directly to implement.

Success Chains

On successful completion chains to: testing · refactor · govern

FSM — Exploration of the unknown with recursive map-making

stateDiagram-v2
    [*] --> UnexplainedFailure
    UnexplainedFailure --> InitialStackProbe
    InitialStackProbe --> HypothesisMap
    HypothesisMap --> InvestigationRoute

    InvestigationRoute --> SafeHypothesis
    InvestigationRoute --> RiskyHypothesis
    InvestigationRoute --> DeadEnd

    SafeHypothesis --> ExpandedRCAMap
    RiskyHypothesis --> ExpandedRCAMap
    DeadEnd --> Backtrack
    Backtrack --> InvestigationRoute

    ExpandedRCAMap --> RootCauseConfidence
    RootCauseConfidence --> DeeperUnknown: symptom of deeper issue
    DeeperUnknown --> InitialStackProbe

    RootCauseConfidence --> [*]: root cause isolated, fix dispatched

Execution Sequence

sequenceDiagram
    participant Orchestrator
    participant Pool (Analytical)
    participant Pool (Mechanical)
    participant Tool (Context)

    Orchestrator->>Pool (Analytical): Allocate Capability Profile
    activate Pool (Analytical)
    Pool (Analytical)->>Tool (Context): Issue Tool Calls (Parallel)
    Tool (Context)-->>Pool (Analytical): Return Data

    alt Shallow Loop
        Pool (Analytical)->>Pool (Analytical): Auto-correct Schema
    else Medium Loop
        Pool (Analytical)->>Pool (Mechanical): Delegate Fixes
    end

    Pool (Analytical)-->>Orchestrator: Synthesis Gate
    deactivate Pool (Analytical)

    opt Deep Loop
        Orchestrator->>Orchestrator: Complete Throw-back to Prior Stage
    end