# Debug

> Investigate a problem, log it to the debug changelog, cross-check past issues, and suggest a non-duplicate fix.

- Skill: `georgeqle/debug` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add georgeqle/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/georgeqle/debug/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: GeorgeQLe (https://skillmd.com/u/georgeqle)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/georgeqle/debug

---


# Debug

Invoke as `$debug`.

Investigate a reported problem, maintain a persistent debug changelog (`docs/debug-changelog.md`), and propose a fix that avoids repeating past solutions.

## Process

1. Parse the error message, stack trace, or bug description.
2. Capture environment context: current branch, recent commits, uncommitted changes.
3. Ensure `docs/debug-changelog.md` exists (create `docs/` directory and file if missing).
4. Read the full debug changelog and search for prior entries matching the current symptom.
5. If a match is found, report what was tried before and whether the recurrence is systemic.
6. Trace the execution path from the symptom to the root cause, reading only files in the chain.
7. Check recent git history for changes that may have introduced the issue.
8. Propose a minimal fix, cross-checking the changelog to avoid repeating a previously failed approach.
9. Apply the fix, write or update tests, and run them to verify.
10. Prepend a structured entry to `docs/debug-changelog.md` with: date, symptom, category, severity, root cause, fix, test results, related entries, and systemic flag.

## Output

- **Problem**: Symptom, new or recurring
- **Root Cause**: file:line, what's wrong, when introduced
- **Fix Applied**: approach, files modified, test results
- **Changelog Updated**: entry added, any cross-references
- **Prevention**: what check would have caught this earlier; systemic follow-up if applicable

## Next-Step Routing

After reporting the debug outcome:

- If the root cause remains unresolved or verification still fails, use **Recommended next command:** `$debug <specific failing symptom>` with the failing command and evidence, or `$investigate <claim>` when the remaining work is broader repo validation.
- If the fix created or modified tracked files, check `.agents/project.json` for `exec-loop`; recommend `$ship` when enabled, or `npx skillpacks install exec-loop` from the project shell when it is not enabled.
- If a systemic follow-up was added to `tasks/todo.md`, check `.agents/project.json` for `exec-loop`; state that the approved task artifact is ready for an execution-loop runner; if runner tooling is missing, recommend installing `exec-loop` with the project package manager.
- If verification passed, no tracked files are dirty, and no systemic follow-up remains, state that no follow-up command is recommended.

## Constraints

- Always read the full debug changelog before proposing a fix.
- Do not refactor unrelated code.
- Never duplicate a previously failed fix without justification.
- If the root cause can't be determined, report what was ruled out.
- Always run tests after applying the fix.


## Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.