Files

T

Brummel 137ec21e26 docs(tdd): wire sibling skills to the new entry path

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>

2026-06-01 16:56:56 +02:00

4.3 KiB

Raw Blame History

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 (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.

4.3 KiB Raw Blame History