Skills/debug/SKILL.md

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.

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. It is also the single source for the carrier and handoff field definitions (Carrier contract / Output format); this skill names the fields but does not redefine them. 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.