Orchestrates persistent, hypothesis-driven debugging sessions across conversations, delegating analysis to subagents and tracking in debug files.
From pbrnpx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
templates/continuation-prompt.md.tmpltemplates/initial-investigation-prompt.md.tmplSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides agentic engineering workflows: eval-first loops, 15-min task decomposition, model routing (Haiku/Sonnet/Opus), AI code reviews, and cost tracking.
STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.
Before ANY tool calls, display this banner:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► DEBUGGING ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
You are running the debug skill. Your job is to run a structured, hypothesis-driven debugging session that persists across conversations. You track every hypothesis, test, and finding in a debug file so work is never lost.
This skill spawns Task(subagent_type: "pbr:debugger") for investigation work.
Reference: skills/shared/context-budget.md for the universal orchestrator rules.
Additionally for this skill:
Debug systematically, not randomly. Every investigation step must have a hypothesis, a test, and a recorded result. No "let me just try this" — every action has a reason and is documented.
Before any file operations, ensure both directories exist by running:
mkdir -p .planning/debug
This handles the case where neither .planning/ nor .planning/debug/ exist yet (debug can be run before other skills that create .planning/). Do NOT skip this step — writing files to a non-existent directory will fail.
Load depth profile: Run node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth to get debug.max_hypothesis_rounds. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
Scan .planning/debug/ for existing debug files:
.planning/debug/
{NNN}-{slug}.md # Each debug session is a file
Read each file's frontmatter to check status:
status: gathering — collecting symptoms from userstatus: investigating — testing hypothesesstatus: fixing — applying fixstatus: verifying — confirming fix worksstatus: resolved — session completeIf active sessions found:
Use the debug-session-select pattern from skills/shared/gate-prompts.md:
question: "Found active debug sessions. Which would you like?"
Generate options dynamically from active sessions:
Handle responses:
If no active sessions found:
If $ARGUMENTS is provided and descriptive:
If $ARGUMENTS is empty or minimal:
Symptom gathering questions (ask as plain text — these are freeform, do NOT use AskUserQuestion):
Optional follow-ups (ask if relevant):
.planning/debug/ for existing filesCreate .planning/debug/{NNN}-{slug}.md:
---
id: "{NNN}"
title: "{issue title}"
status: gathering
created: "{ISO date}"
updated: "{ISO date}"
severity: "{critical|high|medium|low}"
category: "{runtime|build|test|config|integration|unknown}"
---
# Debug Session: {title}
## Symptoms
**Expected:** {expected behavior}
**Actual:** {actual behavior}
**Reproduction:** {steps}
**Onset:** {when it started}
**Scope:** {affected areas}
## Environment
- OS: {detected or reported}
- Runtime: {node version, python version, etc.}
- Relevant config: {any config that matters}
## Investigation Log
### Round 1 (automated)
{This section is filled by debugger}
## Hypotheses
| # | Hypothesis | Status | Evidence |
|---|-----------|--------|----------|
| 1 | {hypothesis} | {testing/confirmed/rejected} | {evidence} |
## Root Cause
{Filled when found}
## Fix Applied
{Filled when fixed}
## Timeline
- {ISO date}: Session created
Display to the user: ◐ Spawning debugger...
Spawn Task(subagent_type: "pbr:debugger") with the prompt template.
Read ${CLAUDE_SKILL_DIR}/templates/initial-investigation-prompt.md.tmpl for the spawn prompt. Fill in the {NNN}, {slug}, and symptom placeholders with values from the debug file created above.
Resuming debug session #{NNN}: {title}
Last state:
- Hypotheses tested: {N}
- Confirmed: {list or "none yet"}
- Rejected: {list}
- Current lead: {most promising hypothesis}
Continuing investigation...
Increment the round counter (resuming counts as a new round). Display to the user: ◐ Spawning debugger (resuming session #{NNN}, round {N})...
Spawn Task(subagent_type: "pbr:debugger") with the continuation prompt template.
Read ${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl for the spawn prompt. Fill in the {NNN}, {slug}, and {paste investigation log...} placeholders with data from the debug file.
When the debugger agent completes, first check for completion markers in the Task() output before routing:
| Marker in Task() Output | Route To |
|---|---|
## DEBUG COMPLETE | ROOT CAUSE FOUND + FIX path |
## ROOT CAUSE FOUND | ROOT CAUSE FOUND (no fix) path |
## DEBUG SESSION PAUSED | CHECKPOINT path |
| No marker found | INCONCLUSIVE path |
Spot-check: Before routing, verify .planning/debug/{NNN}-{slug}.md exists and was recently updated (modified timestamp is newer than the Task() spawn time). If the debug file was not updated, warn: ⚠ Debug file not updated by agent — results may be incomplete.
Display: ✓ Debug session complete — {N} hypotheses tested (read the hypothesis count from the debug file's Hypotheses table).
The debugger returns one of four outcomes:
Root cause identified: {cause}
Fix applied: {description}
Commit: {hash}
Actions:
status: resolved╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► BUG RESOLVED ✓ ║
╚══════════════════════════════════════════════════════════════╝
**Session #{NNN}:** {title}
**Root cause:** {cause}
**Fix:** {description}
**Commit:** {hash}
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Continue your workflow** — the bug is fixed
`/pbr:status`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:continue` — execute next logical step
- `/pbr:review {N}` — verify the current phase
Used when the debugger was invoked with find_root_cause_only or when the fix is too complex for auto-application.
Root cause identified: {cause}
Suggested fix: {approach}
Actions:
status: resolved
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Apply the fix** — root cause identified, fix needed
`/pbr:quick {fix description}`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:plan` — for complex fixes that need planning
- `/pbr:status` — see project status
The debugger found something but needs user input or more investigation.
Investigation progress:
- Tested: {hypotheses tested}
- Found: {key finding}
- Need: {what's needed to continue}
Actions:
skills/shared/gate-prompts.md:
question: "Investigation has reached a checkpoint. How should we proceed?"Handle responses:
◐ Spawning debugger (continuing investigation, round {N})... and spawn another Task(subagent_type: "pbr:debugger") with updated context from the debug fileThe debugger exhausted its hypotheses without finding the root cause.
Investigation exhausted:
- Tested: {all hypotheses}
- Rejected: {list}
- Remaining unknowns: {list}
Actions:
The debugger agent follows this protocol internally:
1. OBSERVE: Read error messages, logs, code around the failure point
2. HYPOTHESIZE: "The most likely cause is X because Y"
3. PREDICT: "If X is the cause, then test Z should show W"
4. TEST: Execute test Z
5. EVALUATE:
- Result matches prediction → hypothesis supported → investigate deeper
- Result contradicts → hypothesis rejected → try next hypothesis
- Result is unexpected → new information → form new hypothesis
| Technique | When to Use |
|---|---|
| Stack trace analysis | Error with stack trace available |
| Code path tracing | Logic error, wrong behavior |
| Log injection | Need to see runtime values |
| Binary search | Know it worked before, need to find when it broke |
| Isolation | Complex system, need to narrow scope |
| Comparison | Works in one case, fails in another |
| Dependency audit | Recent dependency changes |
| Config diff | Works in one environment, not another |
| Quality | Description | Action |
|---|---|---|
| Strong | Directly proves/disproves hypothesis | Record and move on |
| Moderate | Suggests but doesn't prove | Record, seek corroboration |
| Weak | Tangentially related | Note but don't base decisions on it |
| Misleading | Red herring | Record as eliminated, explain why |
The maximum number of investigation rounds is controlled by the depth profile's debug.max_hypothesis_rounds setting:
quick: 3 rounds (fast, surface-level investigation)standard: 5 rounds (default)comprehensive: 10 rounds (deep investigation)The orchestrator tracks the round count. Before spawning each continuation debugger (Step 4 "CHECKPOINT" -> "Continue"), increment the round counter. If the counter reaches the limit:
Use AskUserQuestion: question: "Reached {N}-round hypothesis limit. How should we proceed?" header: "Debug Limit" options: - label: "Extend" description: "Allow {N} more rounds (doubles the limit)" - label: "Wrap up" description: "Record findings so far and close the session" - label: "Escalate" description: "Save context for manual debugging"
status: resolved with resolution: abandoned, record all findings, suggest next stepsgathering → investigating → fixing → verifying → resolved
(any non-resolved) → resolved (with resolution: abandoned, if 7+ days stale)
(any non-resolved) → (same) (resumed after pause)
When scanning for active sessions, check the updated date. If more than 7 days old:
status: resolved with resolution: abandoned in frontmatterOld resolved debug files can accumulate. They serve as a knowledge base for similar issues. Do NOT auto-delete them.
Update STATE.md Debug Sessions section (create if needed):
### Debug Sessions
| # | Issue | Status | Root Cause |
|---|-------|--------|------------|
| 001 | Login timeout | resolved | DB connection pool exhausted |
| 002 | CSS not loading | active | investigating |
Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.
If planning.commit_docs: true in config.json:
docs(planning): open debug session {NNN} - {slug}docs(planning): resolve debug session {NNN} - {root cause summary}fix({scope}): {description}If the debugger Task() fails or returns an error, display:
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Debugger agent failed for session #{NNN}.
**To fix:**
- Check the debug file at `.planning/debug/{NNN}-{slug}.md` for partial findings
- Re-run with `/pbr:debug` to resume the session
- If the issue persists, try a fresh session with different symptom details
debug.max_hypothesis_rounds limit without user confirmation (default: 5 for standard mode)