AgentHubv0.4

Skill · Systematic debugging

A method. Six phases, in order, every time. The skill keeps hub:debugger from guessing — and keeps you from accepting a patch that only hides the symptom.

When it activates

Automatically on every /hub:debugdispatch, and when the main model decides a task is a bug (error keywords, stack traces, “not working,” “fails on CI”).

The six phases

  1. Reproduce.If the bug can't be reproduced, stop and ask for a repro. Don't move to isolate on a theory.
  2. Isolate. Bisect — time (when did it start?), surface (which endpoint / component?), input (which data triggers it?). One axis at a time.
  3. Minimise. Cut the repro to the smallest form that still fails. Throw-away code is fine here; it clarifies the cause.
  4. Root cause. State it as one sentence: “The bug is X because Y.”If you can't, you're still isolating.
  5. Fix.Targeted change. Nothing else. No “while I'm in here” cleanup.
  6. Regression test.A test that fails before the fix and passes after. If there isn't one, the fix is incomplete.

What it refuses

  • Fixes without repro. The agent will ask for one instead of guessing.
  • Refactors outside the blast radius. A one-line bug doesn't need a 40-line file rewrite.
  • Patches that mask the symptom. “Catch the error and log it” is not a fix unless the error is expected.

Example: what the skill produces

Symptom:     POST /api/orders returns 500 every ~20 requests.

1. Reproduce: load test, 100 RPS for 60s. Got 47 failures out of 6000.
2. Isolate:   all failures share user_id ending in 00–09. Rest never fail.
3. Minimise: isolated to a UUID v4 collision check that was using substring
             comparison instead of full equality.
4. Root:     the bug is stale-cache reads returning "" (empty string) which
             substring-matches any short ID prefix.
5. Fix:      change check to strict equality; treat "" as cache miss.
6. Test:     added test that writes "" to cache and asserts cache-miss path.

Pro tips

  • Always include the phase in your review. If the agent jumped from 1 → 4, make it back up.
  • Accept only with a test. No test, no merge. This is the most-broken rule.
  • Save the repro. If it was hard to reproduce, keep the repro — it becomes the regression test.

Next steps