Skip to content
Skills Library
Programming · Analysis

gsd-debug

/gsd-debug

Use when a bug, failing test, or unexpected behaviour needs investigation, especially across sessions or context resets. Isolates it in a debugger subagent with persistent .planning/debug state, unlike skills/systematic-debugging.

Repository
coco ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a bug, failing test, or unexpected behaviour needs investigation, especially across sessions or context resets. Isolates it in a debugger subagent with persistent .planning/debug state, unlike skills/systematic-debugging.

Arguments

/gsd-debug [--diagnose] [issue description]
Original author description

Use when a bug, failing test, or unexpected behaviour needs investigation, especially across sessions or context resets. Isolates it in a debugger subagent with persistent .planning/debug state, unlike skills/systematic-debugging.

How it works

  1. 0. Initialize Context
  2. 1. Check Active Sessions
  3. 2. Gather Symptoms (if new issue)
  4. 3. Spawn gsd-debugger Agent
  5. 4. Handle Agent Return
  6. 5. Spawn Continuation Agent (After Checkpoint or "Fix now")
Original SKILL.md headings · 178 lines, 612 words
SKILL.md preview
---
name: gsd-debug
description: "Use when a bug, failing test, or unexpected behaviour needs investigation, especially across sessions or context resets. Isolates it in a debugger subagent with persistent .planning/debug state, unlike skills/systematic-debugging."
argument-hint: "[--diagnose] [issue description]"
allowed-tools:
  - Read
  - Bash
  - Task
  - AskUserQuestion
---


<objective>
Debug issues using scientific method with subagent isolation.

**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.

**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.

**Flags:**
- `--diagnose` — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.
</objective>

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

<context>
User's issue: $ARGUMENTS

Parse flags from $ARGUMENTS:
- If `--diagnose` is present, set `diagnose_only=true` and remove the flag from the issue description.
- Otherwise, `diagnose_only=false`.

Check for active sessions:
```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
```
</context>

<process>

## 0. Initialize Context

```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

Extract `commit_docs` from init JSON. Resolve debugger model:
```bash
debugger_model=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-debugger --raw)
```

## 1. Check Active Sessions

If active sessions exist AND no $ARGUMENTS:
- List sessions with status, hypothesis, next action
- User picks number to resume OR describes new issue

If $ARGUMENTS provided OR user describes new issue:
- Continue to symptom gathering

## 2. Gather Symptoms (if new issue)

Use AskUserQuestion for each:

1. **Expected behavior** - What should happen?
2. **Actual behavior** - What happens instead?
3. **Error messages** - Any errors? (paste or describe)
4. **Timeline** - When did this start? Ever worked?
5. **Reproduction** - How do you trigger it?

After all gathered, confirm ready to investigate.

## 3. Spawn gsd-debugger Agent

Fill prompt and spawn:

```markdown
<objective>
Investigate issue: {slug}

**Summary:** {trigger}
</objective>

<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>

<mode>
symptoms_prefilled: true
goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
</mode>

<debug_file>
Create: .planning/debug/{slug}.md
</debug_file>
```

```
Task(
  prompt=filled_prompt,
  subagent_type="gsd-debugger",
  model="{debugger_model}",
  description="Debug {slug}"
)
```

## 4. Handle Agent Return

**If `## ROOT CAUSE FOUND` (diagnose-only mode):**
- Display root cause, confidence level, files involved, and suggested fix strategies
- Offer options:
  - "Fix now" — spawn a continuation agent with `goal: find_and_fix` to apply the fix (see step 5)
  - "Plan fix" — suggest `/gsd-plan-phase --gaps`
  - "Manual fix" — done

**If `## DEBUG COMPLETE` (find_and_fix mode):**
- Display root cause and fix summary
- Offer options:
  - "Plan fix" — suggest `/gsd-plan-phase --gaps` if further work needed
  - "Done" — mark resolved

**If `## CHECKPOINT REACHED`:**
- Present checkpoint details to user
- Get user response
- If checkpoint type is `human-verify`:
  - If user confirms fixed: continue so agent can finalize/resolve/archive
  - If user reports issues: continue so agent returns to investigation/fixing
- Spawn continuation agent (see step 5)

**If `## INVESTIGATION INCONCLUSIVE`:**
- Show what was checked and eliminated
- Offer options:
  - "Continue investigating" - spawn new agent with additional context
  - "Manual investigation" - done
  - "Add more context" - gather more symptoms, spawn again

## 5. Spawn Continuation Agent (After Checkpoint or "Fix now")

When user responds to checkpoint OR selects "Fix now" from diagnose-only results, spawn fresh agent:

```markdown
<objective>
Continue debugging {slug}. Evidence is in the debug file.
</objective>

<prior_state>
<files_to_read>
- .planning/debug/{slug}.md (Debug session state)
</files_to_read>
</prior_state>

<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>

<mode>
goal: find_and_fix
</mode>
```

```
Task(
  prompt=continuation_prompt,
  subagent_type="gsd-debugger",
  model="{debugger_model}",
  description="Continue debug {slug}"
)
```

</process>

<success_criteria>
- [ ] Active sessions checked
- [ ] Symptoms gathered (if new)
- [ ] gsd-debugger spawned with context
- [ ] Checkpoints handled correctly
- [ ] Root cause confirmed before fixing
</success_criteria>

Versions

The database has no other skills named gsd-debug.

Database snapshot: 13.11.2026 · package version 9b5f92afa9f9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90systematic-debugging
    Root-cause analysis + bug fixing. Use when user reports bug, error, crash, unexpected behavior, failing test, or asks "debug", "fix this", "why is this happening", "investigate this issue".
  • 100donny-debug
    Systematic root-cause debugging by the scientific method, with session state persisted across context resets. Use when investigating a bug, error, test failure, or unexpected behavior, or resuming a prior debug session; pass --diagnose to find the root cause without applying a fix.
  • 100systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100debug
    Use when encountering any bug, test failure, or unexpected behavior - requires root cause investigation before proposing fixes
  • 100systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100debug
    Diagnose a failing test, build, crash, regression, or unexpected behavior without editing source. Reproduce the symptom, test hypotheses, identify the supported root cause, and hand off a repair. Use for /debug, root-cause investigation, or questions about why something is broken.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.