fix(debug): close the intake gate properly — and the contradiction it exposed
CI / Check / Test (push) Successful in 1s
CI / Tag release (push) Successful in 1s

The GREEN run confirmed the gate works: given "builds are flaky again... what's
the fix?" with no run id and no log, it produced zero hypotheses and an ordered
list of artifacts, each justified by what it would discriminate. It also caught
that the retry already shipped in that pipeline is destroying the evidence
needed to diagnose it, which is a better finding than any hypothesis would have
been.

Then it found eight problems, and the first two are mine:

**The template contradicted the rule.** I banned high/medium/low labels in
Step 2 and left them in the Step 3 output template and all three worked-example
hypotheses. "Prose loses to a format block every time" — correct, and the
template is what gets imitated. Labels are gone from both; the slot is now WHY
FIRST, which asks for the evidence that sets the order rather than a restatement
of it.

**The description never mentioned the gate.** That is the text a harness shows
before an agent decides to load anything, and it read "Generate 3-5 ranked
hypotheses" — so an agent routing on the description alone does exactly the
thing this skill was rewritten to prevent. Both description and use_when now
lead with the refusal.

The rest:

- Intake vs the failed-fixes section pointed opposite ways for a report that
  fires both, and nothing stated precedence. Intake wins, and says so: you
  cannot aim hypotheses at a premise you have no evidence about either.
- "One run narrows the search to a single component" was overclaimed exactly
  where it gets used — CI flakiness. One run *that reproduces* narrows it; a
  passing run narrows nothing.
- session_log had no phase for a correct refusal, so an intake stop logged as a
  failed read-failure. A metric that penalises the skill's best behaviour trains
  the next model to guess. Added an `intake` phase.
- The Anti-Patterns table — the part people scan in a hurry — was missing the
  failure this whole rewrite is about: answering "what's the fix?" from a report
  with no artifact.
- brain_query told you to search on an error string you may have just refused to
  proceed without. Now: query symptom + component, which may itself name the
  artifact to ask for.
- condition-based-waiting was an unconditional load on any mention of a timeout,
  including during an intake stop, which is the wrong side of the gate.

Closes #36
Bump-Type: minor
This commit is contained in:
2026-08-29 15:17:16 +02:00
parent cba0fe4337
commit 0c7fac3686
2 changed files with 29 additions and 14 deletions
+1 -1
View File
@@ -14,7 +14,7 @@ the SKILL.md, not the table.
| `clean-code` | Clean code principles with Go adaptation | Code review, refactoring, new code | claude-code, library |
| `code-review` | Code smell detection + Go-specific checklist | Pre-merge review | claude-code, library |
| `cognitive-load` | Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring | claude-code, library |
| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious | claude-code, library |
| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious — or a bug report with no failure text, which this skill refuses rather than guesses at | claude-code, library |
| `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing | claude-code, library |
| `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index | claude-code, library, chat |
| `experiment-spec` | Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature | claude-code, library |