hm-l2-debug

Files (6)

• SKILL.md
• evals.json · evals/
• rich-gate-scorecard.md · metrics/
• debug-state-machine.md · references/
• evidence-framework.md · references/
• validate-skill.sh · scripts/

SKILL.md (first lines)

## Overview

Systematic debugging workflow that maintains investigation state across context resets. Use when tracing root causes of complex failures, investigating intermittent issues, or performing structured failure analysis. Produces evidence-grounded diagnosis with hypothesis tracking and verification checkpoints.

## The Iron Law

```
NO FIXES BEFORE ROOT-CAUSE INVESTIGATION. Fix the cause, not the symptom. Verify the fix, not the hypothesis.
```

# Systematic Debugging
## On Load

1. Read `references/debug-state-machine.md` — structured debugging protocol
2. Read `references/evidence-framework.md` — how to collect and rank evidence

## The Debug Protocol

### Stop-the-Line Entry Gate

When debugging starts, stop feature work and preserve the failing evidence before changing code. This follows the third-party gated discipline pattern from `NousResearch/hermes-agent` systematic debugging and `addyosmani/agent-skills` debugging recovery guidance: reproduce, localize, reduce, prove root cause, guard recurrence, then resume.

**Required evidence before a fix:**

| Evidence | Required proof |
|----------|----------------|
| Failure capture | Exact command, input, stack trace, log, UI path, or user action that fails |
| Boundary trace | Where data/control enters, transforms, and exits the failing subsystem |
| Competing hypotheses | At least two plausible causes considered, with one selected for falsification |
| Root-cause prediction | “If this cause is true, then this experiment will show X” |
| Recurrence guard | Regression test, monitor, invariant, or documented manual verification that catches repeat failure |

If this evidence does not exist, stay in `REPRODUCE`, `GATHER`, or `ISOLATE`; do not enter `FIX`.

### Step 1: Reproduce

```bash
# Can you make it fail on demand?
# If no → gather more context, ask for reproduction steps
# If yes → proceed to isolation
```

**Gate:** If you cannot reproduce, you cannot verify a fix.

### Step 2: Isolate

```bash
# Binary search: comment out half the code
# Does it still fail?
#   YES → bug is in remaining half
#   NO  → bug is in commented half
# Repeat until single line/function identified
```

**Gate:** If isolation stalls, collect more evidence (logs, traces, inputs).

### Step 3: Hypothesize

Form exactly one hypothesis:

```
HYPOTHESIS: <specific mechanism causing the bug>
PREDICTION: <if hypothesis is true, then X will happen when Y>
```

**Gate:** If you have multiple hypotheses, test them one at a time.

### Step 4: Test Hypothesis

```bash
# Run experiment that distinguishes hypothesis from alternatives
# Record result
```

**Gate:** If experiment is inconclusive, refine hypothesis or gather more data.

### Step 5: Fix and Verify

```bash
# Apply minimal fix
# Reproduce original failure scenario
# Confirm failure is gone
# Run regression tests to ensure no new failures
```

**Gate:** If fix passes but regression tests fail, revert and reconsider.

### Step 6: Guard Recurrence

After verification, add the smallest durable guard that would have caught the bug: regression test, assertion, structured log, invariant check, or runbook note. If the guard is intentionally deferred, write the reason and owner into the debug session state.

## Persistent Debug State

Across context resets, persist:

```markdown
## Debug Session: <bug-id>
**Status:** [reproducing | isolating | hypothesizing | fixing | verified]
**Reproduction:** <exact steps>
**Isolation:** <narrowed to file/function/line>
**Hypothesis:** <current hypothesis>
**Experiments Run:** <list with results>
**Fix Applied:** <commit hash>
**Verification:** <test results>
```

Store in `.debug/<bug-id>.md`.

## RICH Gate Source Decisions

| Source | Decision | Local adaptation |
|--------|----------|------------------|
| `NousResearch/hermes-agent` systematic-debugging | ADOPT | “No fixes before root-cause investigation” is now an explicit iron-law clause. |
| `addyosmani/agent-skills` debugging-and-error-recovery | ADAPT | Stop-the-line, preserve evidence, root-cause fix, and recurrence guard mapped into the debug state machine. |
| GitHub agent skill resource model | ADAPT | Heavy details remain in references/evals; SKILL.md stays as the trigger and gate index. |

## Independence Notes

Default state path is `.debug/<bug-id>.md` in the end-user project. If a project already has a debug/journal convention, use that convention and record the path in the session state. Do not assume GSD, BMAD, or this repository's `.planning/` layout.

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin