AGENTS/.pi/gsd/workflows/debug.md

Debug Context (pre-injected by WXP)

Problem:

Timestamp:

Project State:

Debugger Skills:

---

Systematic debugging session. Diagnoses failures, errors, and unexpected behavior using structured root-cause analysis. Spawns gsd-debugger with full project context for focused investigation.

For post-mortem investigation of completed phases, use /gsd-forensics instead.

<available_agent_types> Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):

• gsd-debugger - Diagnoses and fixes issues </available_agent_types>

Load current phase context:

PHASE_INFO=$(pi-gsd-tools roadmap analyze --raw 2>/dev/null || echo "{}")

Extract from state JSON:

• current_phase - what's being worked on
• last_activity - when was the last change
• milestone - current milestone name

If description is empty, ask the user:

What's broken? Describe the symptom in one sentence:
(e.g. "auth tokens expire immediately", "build fails with missing module", "tests pass locally but fail in CI")

Store response as description.

Classify the issue from the description:

Symptom pattern	Issue type
Error/exception message	runtime_error
Test failures	test_failure
Build/compile error	build_error
Wrong behavior (no error)	logic_error
Performance problem	performance
Integration failure	integration
Unclear	unknown

Set ISSUE_TYPE.

Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DEBUG SESSION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issue: {description} Type: {ISSUE_TYPE} Phase: {current_phase || "not set"}

◆ Spawning debugger...

Resolve model:
```bash
DEBUGGER_MODEL=$(pi-gsd-tools resolve-model gsd-debugger --raw 2>/dev/null || echo "")

Debug prompt:

<objective>
Debug the following issue in this project:
{description}

Issue type: {ISSUE_TYPE}
Current phase: {current_phase}
Milestone: {milestone}
</objective>

<files_to_read>
- .planning/STATE.md (Project state and recent decisions)
- .planning/ROADMAP.md (Phase context)
- ./GEMINI.md or ./CLAUDE.md (Project-specific guidelines, if exists)
</files_to_read>

${AGENT_SKILLS_DEBUGGER}

<investigation_protocol>
1. Reproduce: Identify the minimal steps to trigger the issue
2. Isolate: Narrow down to the failing component/file/function
3. Root cause: Identify WHY it fails, not just WHERE
4. Fix: Implement the smallest change that solves the root cause
5. Verify: Confirm the fix works and doesn't introduce regressions

Always check:
- Recent commits (git log --oneline -10) for what changed
- Related files for mismatched interfaces or broken contracts
- Test suite for existing coverage that should have caught this
</investigation_protocol>

<output_format>
## DEBUG COMPLETE

**Root cause:** [one sentence]
**Fix applied:** [what was changed]
**Files modified:** [list]
**Verification:** [how to confirm it's fixed]

OR

## DEBUG BLOCKED

**Investigated:** [what was tried]
**Blocker:** [what additional info is needed]
**Next step:** [what the human should provide or check]
</output_format>

Task(
  prompt=debug_prompt,
  subagent_type="gsd-debugger",
  model="{DEBUGGER_MODEL}",
  description="Debug: {description}"
)

**`## DEBUG COMPLETE`:**

Display root cause, fix, and verification steps. Offer:

1. Capture as todo (/gsd-add-todo) - if fix not yet applied
2. Continue with current phase (/gsd-execute-phase)
3. Done

## DEBUG BLOCKED:

Display blocker and next steps. Offer:

1. Provide additional context and retry
2. Try forensics mode (/gsd-forensics) - deeper investigation
3. Capture as todo and investigate later

If the debug session produced a fix or useful findings, offer to save:

mkdir -p .planning/debug

Write .planning/debug/{YYYY-MM-DD}-{slug}.md:

---
created: {timestamp}
issue: {description}
type: {ISSUE_TYPE}
phase: {current_phase}
status: {resolved|blocked}
---

## Root Cause
{root cause summary}

## Fix
{what was changed}

## Verification
{how to confirm}

Commit:

pi-gsd-tools commit "docs: debug session - {description_slug}" --files .planning/debug/{filename}

<success_criteria>

• Problem description captured (from arg or prompt)
• Issue classified by type
• gsd-debugger spawned with full project context
• Root cause identified or blocker surfaced
• Fix applied or next steps clear
• Session optionally persisted in .planning/debug/ </success_criteria>