debug

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):
2. Look for status: gaps_found in frontmatter
3. Parse the gaps section for individual gap entries
4. For each gap entry, extract:
5. Gap description (symptom)
6. Expected vs. actual behavior
7. Affected files/components
8. Pre-fill the debug session with UAT context:
9. Issue title: derived from the first/primary gap description
10. Symptoms: populated from gap details (expected, actual, scope)
11. Category: set to the gap's category if available (e.g., "test", "integration")
12. Context: include the phase context and related plan information
13. Skip the symptom-gathering questions in Step 3a (symptoms are already populated from UAT gaps)
14. 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. Reproduction: "How do you trigger this? Steps to reproduce?"
4. Onset: "When did this start? Did anything change recently (new code, dependency update, config change)?"
5. Scope: "Does this affect everything or just specific cases? Any patterns?"

Optional follow-ups (ask if relevant):

• "What have you already tried?"
• "Does this happen in all environments (dev, prod, test)?"
• "Any relevant log output?"

Generate Session ID

1. Scan .planning/debug/ for existing files
2. Extract NNN prefixes
3. Next number = highest + 1 (start at 001)
4. Generate slug from issue title via CLI:

``bash pbr-tools slug-generate "{issue title}" ` Parse the JSON output to get the slug` field.

Create Debug File

CRITICAL (no hook) -- DO NOT SKIP: Write debug session file to disk.

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

Spawn Debugger

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.

Step 3b: Resume Flow

1. Read the debug file content
2. Parse the investigation log and hypotheses table
3. Display to