Debug
Investigate and fix the issue described in "$ARGUMENTS" using systematic root cause analysis. No guessing — find the cause before attempting fixes.
Prerequisites
Stack. Before you build, test, lint, run or generate code, read the Stack section of the project's AGENTS.md, or of CLAUDE.md when AGENTS.md has none. Use its commands exactly as written, its layout for where files go and its rules as requirements. If it names a profile, also read the file <profile>.md in the stacks folder of this skill's bundled references for the full commands, layout and rules; the project's own keys win where both speak. If there is no Stack section, run the singular-detect skill, state what you inferred in one line, and offer to write the section with singular-init. Never assume a package manager, test runner or formatter the project did not declare.
None — this is a utility skill that can run anytime a bug is encountered.
Process
Phase 1: Investigation
Read error messages carefully:
- Read the full error output, stack trace, and any warnings
- Note file paths, line numbers, and error codes
- Don't skip past errors — they often contain the solution
Reproduce the issue:
- Identify the exact steps to trigger the bug
- Can it be triggered reliably?
- If not reproducible, gather more data before proceeding
Check recent changes:
- What changed recently that could cause this? (git log, git diff)
- New dependencies, config changes, environment differences?
Phase 2: Analysis
Trace the data flow:
- Where does the bad value originate?
- Trace backward through the call stack to the source
- Fix at the source, not at the symptom
Find working examples:
- Is there similar code that works correctly?
- What's different between working and broken?
Phase 3: Hypothesis
Form a single hypothesis:
- State clearly: "I think X is the root cause because Y"
- Be specific, not vague
Test minimally:
- Make the smallest possible change to test the hypothesis
- One variable at a time
- If it doesn't work, form a NEW hypothesis — don't pile fixes
Phase 4: Fix
Write a failing test that reproduces the bug
Implement the fix — address the root cause, not the symptom
Verify:
- The failing test now passes
- No other tests broke
- The original issue is resolved
Commit the fix with a clear message explaining what was wrong and why
References
references/stacks/bun-react-ts.md and references/stacks/rust-gpui.md: the shipped stack profiles
Output
Present findings to the user:
- What the root cause was
- What was changed to fix it
- The commit hash
- Any related issues discovered during investigation
1---2name: development-debug3description: Investigate a bug to its root cause systematically — reproduce, trace the data flow, test one hypothesis at a time — then fix it with a regression test. Use when something is broken and the user has a symptom or error message to chase down.4metadata:5 source: https://skillmd.com/skills/bromso/development-debug6 argument-hint: "<symptom or error>"7 stack-aware: true8---910# Debug1112Investigate and fix the issue described in "$ARGUMENTS" using systematic root cause analysis. No guessing — find the cause before attempting fixes.1314## Prerequisites1516**Stack.** Before you build, test, lint, run or generate code, read the `Stack` section of the project's `AGENTS.md`, or of `CLAUDE.md` when `AGENTS.md` has none. Use its commands exactly as written, its `layout` for where files go and its `rules` as requirements. If it names a `profile`, also read the file `<profile>.md` in the `stacks` folder of this skill's bundled references for the full commands, layout and rules; the project's own keys win where both speak. If there is no `Stack` section, run the `singular-detect` skill, state what you inferred in one line, and offer to write the section with `singular-init`. Never assume a package manager, test runner or formatter the project did not declare.1718None — this is a utility skill that can run anytime a bug is encountered.1920## Process2122### Phase 1: Investigation23241. **Read error messages carefully:**25 - Read the full error output, stack trace, and any warnings26 - Note file paths, line numbers, and error codes27 - Don't skip past errors — they often contain the solution28292. **Reproduce the issue:**30 - Identify the exact steps to trigger the bug31 - Can it be triggered reliably?32 - If not reproducible, gather more data before proceeding33343. **Check recent changes:**35 - What changed recently that could cause this? (git log, git diff)36 - New dependencies, config changes, environment differences?3738### Phase 2: Analysis39404. **Trace the data flow:**41 - Where does the bad value originate?42 - Trace backward through the call stack to the source43 - Fix at the source, not at the symptom44455. **Find working examples:**46 - Is there similar code that works correctly?47 - What's different between working and broken?4849### Phase 3: Hypothesis50516. **Form a single hypothesis:**52 - State clearly: "I think X is the root cause because Y"53 - Be specific, not vague54557. **Test minimally:**56 - Make the smallest possible change to test the hypothesis57 - One variable at a time58 - If it doesn't work, form a NEW hypothesis — don't pile fixes5960### Phase 4: Fix61628. **Write a failing test** that reproduces the bug63649. **Implement the fix** — address the root cause, not the symptom656610. **Verify:**67 - The failing test now passes68 - No other tests broke69 - The original issue is resolved707111. **Commit** the fix with a clear message explaining what was wrong and why7273## References7475- `references/stacks/bun-react-ts.md` and `references/stacks/rust-gpui.md`: the shipped stack profiles7677## Output7879Present findings to the user:80- What the root cause was81- What was changed to fix it82- The commit hash83- Any related issues discovered during investigation