datit309/supergraph / plugins/supergraph/skills/diagnose
diagnose
UnverifiedStructured 6-phase debugging. Build feedback loop first, reproduce deterministically, hypothesize with ranked falsifiable theories, instrument one variable at a time, fix with regression test, cleanup. Use when a bug exists, tests fail unexpectedly, or behavior is wrong and cause is unknown.
/supergraph:diagnose
Systematic debugging. Never guess and patch β build a feedback loop, prove the hypothesis, fix once.
Announce: "π /supergraph:diagnose β building feedback loop..."
Setup
Read .supergraph-env for test/lint commands (if exists):
[ -f .supergraph-env ] && source .supergraph-env
This sets $TEST_CMD, $FOCUSED_TEST_CMD, $LINT_CMD. If absent, detect from project config (package.json β jest/vitest, pubspec.yaml β flutter test, etc.) same as /supergraph:scan.
Phases
Phase 1 β Build Feedback Loop
Before touching any code, establish a fast, deterministic way to observe the bug.
# Identify the smallest command that shows the failure
$TEST_CMD --grep "<failing test name>" # focused test run
# or
<minimal repro command>
Goal: failure visible in < 5 seconds. If not, slim down the repro. Do NOT skip this phase. Debugging without a feedback loop is guessing.
Phase 2 β Reproduce Cleanly
- Run the feedback loop 3 times β confirm it fails consistently
- Capture exact error output, stack trace, exit code
- Note any flakiness β treat as separate bug before continuing
- Add a failing regression test if one doesn't exist:
test("<bug description>", () => { ... }) // RED
Phase 3 β Hypothesize (3-5 ranked theories)
List falsifiable hypotheses, ordered most-to-least likely:
1. [Most likely] β [reason] β [how to falsify]
2. [Second] β [reason] β [how to falsify]
3. [Third] β [reason] β [how to falsify]
Rules:
- Each hypothesis must be falsifiable (observable test to disprove it)
- No implementation yet β only theories
- Use graph context if available:
search_graph(project=CBM_PROJECT, name_pattern=<suspect>) trace_path(project=CBM_PROJECT, direction="inbound") trace_path(project=CBM_PROJECT, direction="outbound")
Phase 4 β Instrument (one variable at a time)
Test hypothesis #1 first. Change ONE thing to observe ONE signal:
- Add targeted log/assertion near the suspect code
- Run feedback loop β confirm or refute
- Remove instrumentation after each test β never accumulate debug logs
- If refuted β move to hypothesis #2
- Stop when hypothesis is confirmed
Rule: Never change the code under test and the instrumentation simultaneously.
Phase 5 β Fix + Regression Test
Once root cause is confirmed:
- Write/update the regression test first (stays RED)
- Apply minimal fix
- Run feedback loop β GREEN
- Run full test suite β no regressions
- Run lint:
$LINT_CMD
Minimal fix means: fix the cause, not the symptom. If the fix touches a hub node β get user approval first.
If search/trace returns empty, label graph evidence unavailable and fall back to
Serena/filesystem evidence. Use the validated test-gaps recipe for missing tests.
Phase 6 β Cleanup + Post-mortem
- Remove all debug instrumentation and temp files
- Update CONTEXT.md if bug revealed a hidden domain invariant
- One-sentence post-mortem:
Root cause: [X] Fix: [Y] Prevented recurrence by: [regression test / invariant documented] - Checkpoint:
git add [exact files] git commit -m "fix: <description>"
Report
β
/supergraph:diagnose complete
- Root cause: [confirmed hypothesis]
- Fix: [what changed]
- Regression test: [test name / path]
- Tests: PASS | Lint: PASS
- Next: /supergraph:fix (if more issues) or /supergraph:verify
Rules
- Never skip Phase 1 β feedback loop is mandatory
- Never change two variables simultaneously in Phase 4
- Never commit without a regression test
- If hypotheses exhausted with no match β stop, report to user with all observations
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |