PAL Debug is a systematic root cause analysis tool designed for complex software issues. It leverages a hypothesis-driven workflow to investigate race conditions, memory leaks, and integration failures through structured multi-step debugging and expert validation, ensuring a logical path from problem identification to confirmed resolution.

When should I use pal-debug?

pal-debug is useful in the following scenarios: • Troubleshooting intermittent race conditions and timing issues in multi-threaded or concurrent applications. • Identifying and isolating the source of memory leaks or performance degradation in long-running systems. • Diagnosing complex integration failures and data inconsistencies between distributed microservices or third-party APIs. • Conducting deep-dive root cause analysis for mysterious production errors where standard debugging attempts have reached a dead end.

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:

# 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

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

pal-debug

When & Why to Use This Skill

Use Cases