---

name: pal-debug description: Systematic debugging and root cause analysis using PAL MCP. Use for complex bugs, mysterious errors, race conditions, memory leaks, and integration problems. Triggers on debugging requests, error investigation, or when stuck on difficult issues.

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:

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

Optional Parameters

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

CopyStep 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

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