Agent skill

pal-debug

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/pal-debug

SKILL.md

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:

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

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

Didn't find tool you were looking for?

Be as detailed as possible for better results