graphify-recurring-bugs

# Graphify-Aware Recurring Bugs ## Overview A stack trace shows where a bug surfaced, not everywhere its root cause reaches. Grepping around the crash site misses related call sites that share the same underlying problem — which is exactly how the same root cause gets logged as three unrelated "new" bugs over time. `graphify` already builds a queryable structural map of a codebase; this skill puts that map to work specifically during bug investigation, not just general code Q&A. **Core principle:** a recurring bug should be recognized as recurring — and its known-good fix reused — not re-discovered as new. graphify is the linker that recalls the past occurrence; `KNOWN_ISSUES.md` is where the fix that worked is actually recorded. ## Gate: does this apply? Check for `graphify-out/graph.json` at the project root before doing anything else in this skill. - **Missing** → this skill is a complete no-op. Don't suggest building a graph mid-investigation (that's a real side effect — leave it to `/craftsman:init`'s ask-first note, or to the user deciding to run `graphify .` themselves). Proceed with normal root-cause investigation. - **Present** → continue below. ## During root-cause investigation This slots into the evidence-gathering step of root-cause investigation (Phase 1 of the superpowers `systematic-debugging` skill, where that plugin is installed) — run this *before* falling back to raw grep: 1. `graphify query "<symptom or affected function/file>"` — get a scoped subgraph of related code. This is both cheaper in tokens than grepping the whole codebase and more thorough than reading only the stack trace, since it surfaces callers/dependents that share the same code path. 2. If the query surfaces other call sites of the same function/module implicated in the bug, treat them as suspects too — a bug in a shared helper usually isn't confined to the one call site that happened to trigger it first. ## Before filing a new KNOWN_ISSUES.md entry (and recall a past fix) Don't file blind. For each existing entry in the project's `KNOWN_ISSUES.md` — **open and resolved** — check for a structural link: 1. `graphify path "<new bug's file/symbol>" "<existing entry's file/symbol>"` — a short path (direct call, shared callee, same module) is a signal the new bug may be the *same* root cause resurfacing at a different call site. 2. If a short path is found, surface it explicitly: "this looks related to the entry from <date> — same root cause via `<path>`, not a new issue." Let the user or the fix decide whether to merge, not an automatic merge — this is a heuristic signal, not a certainty. 3. When the match lands on a **resolved** entry, that entry's one-line "how it was fixed" is a known-good fix for this recurrence — surface it and reuse it rather than re-deriving the fix from scratch. (graphify recalls *which* past issue is relevant; the fix text itself lives in `KNOWN_ISSUES.md`, not the graph.) 4. Only file a genuinely new entry once existing ones are ruled out this way. ## After the fix Run `graphify update .` (incremental, AST-only extraction — no LLM cost) so the graph reflects the fix for the next investigation. This mirrors the same rule some projects already keep in their own `CLAUDE.md`; this skill makes it apply everywhere a graph exists, not just one project. ## What this does not do - Does not build or rebuild a graph from scratch — that's a real side effect gated behind explicit user action (`graphify <path>`), never triggered implicitly by a bug investigation. - Does not replace root-cause analysis — it's evidence-gathering *within* the investigation, not a substitute for establishing the cause before fixing. - Does not auto-resolve or auto-merge `KNOWN_ISSUES.md` entries — it only surfaces a possible relationship for a human (or the coder agent, with the user's judgment) to confirm.