PAL Debug - Root Cause Analysis

Systematic debugging with hypothesis testing and expert validation through the PAL MCP server.

When to Use

• Complex bugs that aren't obvious
• Mysterious errors with unclear causes
• Race conditions or timing issues
• Memory leaks or performance problems
• Integration failures between systems
• When you've tried basic debugging and are stuck

Quick Start

Use the mcp__pal__debug tool for multi-step investigation:

# Step 1: Start investigation
result = mcp__pal__debug(
    step="Investigating: API returns 500 on concurrent requests",
    step_number=1,
    total_steps=3,
    next_step_required=True,
    findings="Initial investigation - gathering context",
    hypothesis="Unknown - needs investigation",
    confidence="exploring",
    relevant_files=["/path/to/api/handler.py"]
)

# Step 2+: Continue with continuation_id
result = mcp__pal__debug(
    step="Found evidence in logs showing connection pool exhaustion",
    step_number=2,
    total_steps=3,
    next_step_required=True,
    findings="Connection pool limit reached under load",
    hypothesis="Database connection pool too small for concurrent requests",
    confidence="high",
    continuation_id=result["continuation_id"]
)

Required Parameters

| Parameter | Type | Description | |-----------|------|-------------| | step | string | Current investigation narrative | | step_number | int | Current step (starts at 1) | | total_steps | int | Estimated total steps needed | | next_step_required | bool | True if more investigation needed | | findings | string | Evidence and discoveries |

Optional Parameters

| Parameter | Type | Description | |-----------|------|-------------| | hypothesis | string | Current root cause theory | | confidence | enum | exploring/low/medium/high/very_high/almost_certain/certain | | relevant_files | list | Absolute paths to relevant files | | files_checked | list | All files examined | | issues_found | list | Issues with severity levels | | continuation_id | string | Continue previous session | | model | string | Override model (default: openai/gpt-5) | | thinking_mode | enum | minimal/low/medium/high/max |

Confidence Levels

• exploring - Just starting, no theory yet
• low - Early hypothesis, little evidence
• medium - Some supporting evidence
• high - Strong evidence for theory
• very_high - Very confident, need verification
• almost_certain - Nearly confirmed
• certain - 100% confirmed (skips external validation)

Workflow Pattern

Step 1: State the problem and initial direction
        ↓
Step 2: Gather evidence, form hypothesis
        ↓
Step 3: Test hypothesis, refine or pivot
        ↓
Step N: Confirm root cause, propose fix

Example: Database Connection Issue

# Start
mcp__pal__debug(
    step="API returning 500 errors under load. Starting investigation.",
    step_number=1,
    total_steps=4,
    next_step_required=True,
    findings="Errors correlate with high traffic periods",
    hypothesis="Resource exhaustion under load",
    confidence="exploring",
    relevant_files=[
        "/app/api/routes.py",
        "/app/db/connection.py"
    ]
)

Best Practices

1. Start broad, narrow down - Don't assume the cause upfront
2. Document everything - Track files checked, even dead ends
3. Update hypothesis - Revise as new evidence emerges
4. Use continuation_id - Preserve context across steps
5. Set realistic steps - Adjust total_steps as complexity reveals itself