Brummel
26e9630496
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing). Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign. Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
4.2 KiB
name, description
| name | description |
|---|---|
| debug | Use when a bug surfaces — failing test, segfault, wrong stdout, panic, or any observable misbehaviour. Bug fixes are RED-first TDD; no fix is attempted before the failing test exists in the working tree. Mandatory for any bug, including ones that look trivial. |
debug — RED-first bug diagnoser
Violating the letter of these rules is violating the spirit.
Overview
Bugs are diagnosed and fixed by a two-stage handoff: this
skill produces the RED test and the cause analysis; the
implement skill then drives the fix to GREEN. Skipping the
RED stage — even for "trivial" bugs — produces fixes that don't
stick and tests that don't exist to catch the next regression.
The substantive process — root cause investigation → pattern
analysis → minimal, autonomous RED test → handoff, plus the
Phase 4.5 architecture-question trigger after three failed
hypotheses — lives in agents/debugger.md. The RED stage is
not "any failing test": Phase 3 reduces the reproducer to the
smallest autonomous trigger before the test counts. That file is the single source of truth
for the discipline; this skill file only governs trigger,
dispatch, and handoff.
When to Use / Skipping
Trigger this skill on:
- a failing run of the project's test command (its CLAUDE.md project facts)
- wrong stdout from running a project artefact
- a segfault from a built binary
- a panic / unhandled exception in the toolchain
- a structured diagnostic from
bencherorarchitectthat names a concrete misbehaviour
Never skipped. A bug without a regression test is a code change, not a fix. Ad-hoc judgement that a bug is "too small for TDD" is the exact failure mode this skill exists to prevent.
debug is for a regression of existing behaviour. New
test-specifiable behaviour is its sibling tdd's job (same
two-stage RED→GREEN shape, triggered by a feature description
rather than an observed misbehaviour) — route there instead.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
NO FIX WITHOUT A FAILING TEST FIRST
Both clauses are non-negotiable.
Dispatch
Dispatch the debugger agent with the carrier fields it defines
under Carrier contract in agents/debugger.md — symptom,
repro_known, recent_iter. That table is the authoritative
definition of those fields; it is deliberately not restated here,
so the two files cannot drift.
The agent writes the RED test to the working tree (uncommitted)
and reports the handoff carrier for implement mini-mode. The
agent does NOT commit anything, and does NOT write the fix —
splitting RED (this skill) and GREEN (implement mini-mode)
across two dispatches keeps the diagnosis honest. The
orchestrator decides whether to commit the RED test as a
separate audit-trail commit before dispatching implement
mini-mode, or to hand the dirty working tree directly to
mini-mode (the mini-mode orchestrator's Phase-0 clean-tree
check will refuse the latter — so for an audit-trail-preserving
flow the orchestrator commits the RED test first; for a
streamlined-fix flow the orchestrator commits the combined
RED+GREEN at the end of mini-mode).
Handoff Contract
debug produces, for implement mini-mode, the handoff carrier
the agent defines under Output format in agents/debugger.md
— red_test_path, cause_summary, constraint. That list is
the authoritative definition of those fields; it is deliberately
not restated here, so the two files cannot drift.
Anything else (broader refactor, doc rewrite, new feature) is OUT of scope for the bug-fix iteration and gets queued for a separate one.
Cross-references
- Agent dispatched:
agents/debugger.md— carries the four-phase process, the Phase 4.5 escalation rule, the Common Rationalisations table, and the Red Flags list. The orchestrator does not execute these phases directly. - Hand-off target:
../implement/SKILL.md— runs the GREEN side after the orchestrator has decided whether to commit the RED test separately or as part of the final fix commit. - Sibling RED-first skill:
../tdd/SKILL.md— same two-stage RED→GREEN handoff toimplementmini-mode, but triggered by a new test-specifiable behaviour rather than an observed bug.