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