Brummel
137ec21e26
The tdd skill referenced its neighbours (implement, brainstorm, debug) but none referenced it back. Close the loop so the new executable-spec-first entry path is reachable and consistent from every skill that describes a relationship it now belongs to: - implement: mini-mode trigger + dispatch example now cover a RED-first handoff from `debug` OR `tdd` (was debug-only); the orchestrator's task template and Phase-3 skip note generalised. This was real drift — mini-mode is no longer debug-exclusive. - planner: skip rule gains the `tdd` case (it skips brainstorm AND planner — the RED executable-spec is the plan). - brainstorm: `tdd` added to the permitted-skip list as the profile-gated alternative entry path, plus a cross-ref marking brainstorm as the bounce-back target when behaviour stops being test-specifiable. - boss: pipeline diagram, Step-3 routing prose, and cross-refs. A test-specifiable feature issue is dispatched to `tdd` autonomously, the same way a bug issue goes to `debug`; this is NOT a new-cycle bounce-back (the test is the spec). The bounce-back fires only reactively, when tdd surfaces a genuine design fork. - debug: reciprocal sibling note + cross-ref (new behaviour is tdd's job; debug is for regressions of existing behaviour). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
106 lines
4.3 KiB
Markdown
106 lines
4.3 KiB
Markdown
---
|
|
name: debug
|
|
description: 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 (configured under
|
|
`commands.test` in the profile)
|
|
- wrong stdout from running a project artefact
|
|
- a segfault from a built binary
|
|
- a panic / unhandled exception in the toolchain
|
|
- a structured diagnostic from `bencher` or `architect` that
|
|
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,
|
|
on profiles that enable it.
|
|
|
|
## 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 to `implement` mini-mode, but
|
|
triggered by a new test-specifiable behaviour rather than an
|
|
observed bug.
|