Skip to content

datit309/supergraph / plugins/supergraph/skills/diagnose

diagnose

Verified

Structured 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.

FileKindSize
SKILL.mdskill md4.0 KB
---
name: diagnose
description: Structured 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.
mcp: codebase-memory-mcp
---

# /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):**
```bash
[ -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.

```bash
# 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:

1. Write/update the regression test first (stays RED)
2. Apply minimal fix
3. Run feedback loop β†’ GREEN
4. Run full test suite β†’ no regressions
5. 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:
  ```bash
  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
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall