/debug

name: debug
description: "Systematic debugging with hypothesis testing. Persistent across sessions."
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "[issue description]"

**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.**

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► DEBUGGING                                  ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:debug — Systematic Debugging

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.

---

References

• `references/questioning.md` — Investigation questioning patterns: progressive depth, exploratory questions, concrete options (not open-ended)
• `references/ui-brand.md` — Status symbols, banners, error boxes for issue reporting

---

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• **Never** perform investigation work yourself — delegate ALL analysis to the debugger subagent
• **Minimize** reading debug file content — read only the latest hypothesis and result section
• **Delegate** all code reading, hypothesis testing, and fix attempts to the debugger subagent

---

Core Principle

**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.

---

Flow

Step 1: Ensure Debug Directory Exists

**CRITICAL (no hook) -- DO NOT SKIP: Create debug directory before any file writes.**

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.

Step 2: Check for Active Debug Sessions

**Load depth profile:** Run `pbr-tools 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 user
• `status: investigating` — testing hypotheses
• `status: fixing` — applying fix
• `status: verifying` — confirming fix works
• `status: resolved` — session complete

**If active sessions found:**

**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding: 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:

• Each active session becomes an option: label "#{NNN}: {title}", description "Started {date}, last: {last hypothesis}"
• Always include "New session" as the last option: description "Start a fresh debug investigation"
• If more than 3 active sessions exist, show only the 3 most recent plus "New session" (max 4 options)

Handle responses:

• If user selects an existing session: go to **Resume Flow** (Step 3b)
• If user selects "New session": go to **New Session Flow** (Step 3a)
• If user types a session number not in the list: look it up and resume it

**If no active sessions found:**

• Go to **New Session Flow** (Step 3a)

Step 2b: UAT Gap Intake (conditional)

**Trigger:** If `$ARGUMENTS` contains `--from-uat`, OR if no arguments provided and UAT.md gaps exist for the current phase.

When triggered:

1. Read the current phase's VERIFICATION.md (or UAT.md if it exists):

• Look for `status: gaps_found` in frontmatter
• Parse the gaps section for individual gap entries

2. For each gap entry, extract:

• Gap description (symptom)
• Expected vs. actual behavior
• Affected files/components

3. Pre-fill the debug session with UAT context:

• **Issue title**: derived from the first/primary gap description
• **Symptoms**: populated from gap details (expected, actual, scope)
• **Category**: set to the gap's category if available (e.g., "test", "integration")
• **Context**: include the phase context and related plan information

4. Skip the symptom-gathering questions in Step 3a (symptoms are already populated from UAT gaps) 5. Proceed directly to **Generate Session ID** and **Create Debug File** with the pre-filled data

**If `--from-uat` is specified but no gaps exist:**

• Display: "No UAT/verification gaps found for the current phase. Starting a standard debug session."
• Fall through to normal Step 3a flow

Step 3a: New Session Flow

Gather Symptoms

If `$ARGUMENTS` is provided and descriptive:

• Use it as the initial issue description
• Still ask targeted follow-up questions

If `$ARGUMENTS` is empty or minimal:

• Ask the user for symptoms

**Symptom gathering questions** (ask as plain text — these are freeform, do NOT use AskUserQuestion):

1. **Expected behavior**: "What should happen?" 2. **Actual behavior**: "What actually happens? Include error messages if any." 3. **Reprodu