coograph-debug
/coograph-debug
Root-cause a bug or build error with minimal investigation, then apply the smallest fix. Reproduce, gather evidence, fix, verify, with a 3-attempt circuit breaker. Use for failing builds, tests, or runtime errors.
- Author
- paullukic ↗
- Repository
- coograph ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Root-cause a bug or build error with minimal investigation, then apply the smallest fix. Reproduce, gather evidence, fix, verify, with a 3-attempt circuit breaker. Use for failing builds, tests, or runtime errors.
Original author description
Root-cause a bug or build error with minimal investigation, then apply the smallest fix. Reproduce, gather evidence, fix, verify, with a 3-attempt circuit breaker. Use for failing builds, tests, or runtime errors.
How it works
- Phase 0 — Orient with Code-Graph (MANDATORY — non-negotiable)
- Protocol
- Circuit Breaker
- Rules
- Output Format
- Failure Modes to Avoid
- Models
SKILL.md preview
---
name: coograph-debug
description: Root-cause a bug or build error with minimal investigation, then apply the smallest fix. Reproduce, gather evidence, fix, verify, with a 3-attempt circuit breaker. Use for failing builds, tests, or runtime errors.
---
Diagnose the bug or build error below. Find the root cause with minimal investigation, then apply the smallest possible fix.
## Phase 0 — Orient with Code-Graph (MANDATORY — non-negotiable)
**Before reading any file or running any search**, this is the HARD RULE — code-graph first, no exceptions:
1. Call `get_minimal_context(task="debug <symptom>")` then `detect_changes()`. ALWAYS start here. Use `detect_changes()` risk scores first — recent high-risk changes are the most likely culprit. Use the returned file list to focus investigation.
2. Fall back to `sqlite3 .code-graph/graph.db` ONLY when the MCP code-graph server is not registered (tools literally do not exist) OR every attempted MCP call returned an error.
3. Fall back to standard search/read tools ONLY when Step 1 AND Step 2 are both impossible because the code-graph DB is absent from the workspace.
"Slow", "unwieldy", "it's a simple bug" are NOT valid reasons to bypass. When tracing call chains use `query_graph("callers_of", fn)` and `query_graph("callees_of", fn)` before reading files. Validate every hypothesis directly in source regardless of graph output.
## Protocol
### For Runtime Bugs
1. **REPRODUCE**: Can you trigger it reliably? What is the minimal reproduction? Consistent or intermittent?
2. **GATHER EVIDENCE** (parallel when possible):
- Read full error messages and stack traces — every word, not just the first line.
- Check recent changes: `git log --oneline -10`, `git blame` on suspect lines.
- Find working examples of similar code in the codebase.
- Read the actual code at error locations.
3. **HYPOTHESIZE**: Compare broken vs working code. Trace data flow from input to error. Document one hypothesis before investigating further. Identify what test would prove/disprove it.
4. **FIX**: Apply ONE change. Predict the test that proves the fix. Check for the same pattern elsewhere.
5. **VERIFY**: Run the failing test/build to confirm the fix works. Verify no regressions.
### For Build/Compilation Errors
1. Detect project type from manifest files (package.json, pom.xml, Cargo.toml, go.mod, pyproject.toml).
2. Collect ALL errors — run the full build command, not just the first file.
3. Categorize: type inference, missing definitions, import/export, configuration.
4. Fix each error with the minimal change. Verify after each.
5. Final verification: full build exits 0. Report "X/Y errors fixed" after each fix.
## Circuit Breaker
After 3 failed hypotheses, **STOP**. Report what was tried and ask for direction. Do not keep trying variations of the same approach.
## Rules
- Reproduce BEFORE investigating. If you cannot reproduce, find the conditions first.
- One hypothesis at a time. Do not bundle multiple fixes.
- No speculation — "seems like" and "probably" are not findings. Show evidence or drop the claim.
- Fix with minimal diff. Do not refactor, rename, optimize, or redesign while fixing.
- **Scope check after every fix**: review your diff before declaring done. Revert any change not directly related to the root cause.
- Follow all rules and conventions in `AGENTS.md` § Hard rules and `.github/copilot-instructions.md` (when `AGENTS.md` has no Hard rules section, `.github/copilot-instructions.md` holds them all).
## Output Format
### Runtime Bug:
```
## Bug Report
**Symptom**: [What the user sees]
**Root Cause**: [The actual issue at file:line]
**Reproduction**: [Minimal steps to trigger]
**Fix**: [Minimal code change applied]
**Verification**: [How it was proven fixed]
**Similar Issues**: [Other places this pattern might exist]
**Gotcha candidate**: [none, or a GOTCHAS.md entry when the root cause was a trap the code does not show]
```
**Gotcha candidate.** When the root cause was environmental or non-obvious (a tool that ignores the shell environment, a deploy setting, an error message that points the wrong way), draft a `GOTCHAS.md` entry in the format in `.github/layout/README.md`: `Symptom` with the exact error text, `Cause`, `Fix / rule`, `paths:` globs for where it bites, `commands:` if a command triggers it, `confirmed:` today. Show it and ask before writing it to `GOTCHAS.md`. A bug that was just a bug gets `none`.
### Build Error:
```
## Build Error Resolution
**Initial Errors**: X
**Errors Fixed**: Y
**Build Status**: PASSING / FAILING
### Errors Fixed
1. src/file.ts:45 — [error message] — Fix: [what was changed]
### Verification
- Build command: [command] → exit code 0
- No new errors introduced: confirmed
```
## Failure Modes to Avoid
- Symptom fixing: adding null checks everywhere instead of asking "why is it null?"
- Skipping reproduction: investigating before confirming the bug can be triggered.
- Hypothesis stacking: trying 3 fixes at once instead of one at a time.
- Refactoring while fixing: "while I'm fixing this, let me also rename…" — no.
- Infinite loop: same failed approach after 3 attempts. Stop and ask.
$ARGUMENTS
## Models
Read the `models` block in `openspec/config.yaml` before delegating. When `mode` is
`preset` or `per-task`, pass that agent's model on the Agent call; when it is `off`
or `unset`, pass nothing and let the agent inherit the session model.
End your report with one line naming what ran where, so the setting is visible
without reading config:
```
models: reviewer=opus (mapping), explore=haiku (mapping)
```
Print the footer in every mode. In `off` and `unset` it reads `(inherited)`.
Versions
The database has no other skills named coograph-debug.
Database snapshot: 13.11.2026 · package version 6d77408224e3 (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
- 100sdlc-debug
Bug track: reproduce, find the root cause with evidence, write a failing regression test, apply the smallest fix, check siblings, verify on the real surface. Use when something behaves wrongly, a test fails, an error is reported, or the user says 'debug', 'fix this bug' or 'why does X happen'. - 95pstack-bug-fix
pstack bug-fix playbook: reproduce a defect, root-cause it with runtime evidence, land a failing test before the smallest fix, and verify on the same surface. Use for /pstack-bug-fix or when asked to fix a bug the pstack way. - 90investigate-bug
Start of every bug, before any fix. Read the report (often a Notion card), gather the evidence, reproduce the bug when possible, find the root cause and report it with the smallest fix proposed. Use whenever a bug, an incident or a customer complaint comes in, or when someone… - 100debug
Debug a bug, failing test or build, crash, or error. Reproduce it, find the root cause before proposing a fix, prove the fix with the smallest check, add a regression test. Use when something is broken and you need to know why. - 100verify-and-fix
This skill should be used when the user reports an error, bug, or unexpected behavior and wants it diagnosed and fixed. Trigger on phrases like "check this error", "check this bug", "here's an error", "here's a bug", "I have an error", "I have a bug", "found a bug", "got an… - 100debugging-playbook
Debug a reported bug step by step. Reproduce it, isolate the cause with logs, bisection and minimal cases, apply the smallest fix, then add a regression test that fails before the fix. Use when the user reports an error, stack trace, failing test, crash, wrong output, flaky…