Brummel
64b0841c5a
The four-phase debug process and the five-phase fieldtest process each lived twice — once in SKILL.md (orchestrator-facing) and once in the dispatched agent's file (subagent-facing). The orchestrator does not execute these phases; the subagent does. Duplicating them in SKILL.md just bloated the orchestrator's main context with bytes that only the subagent ever needs. SKILL.md now carries only what the orchestrator must consult at dispatch time: trigger gating, Iron Law as headline, the carrier contract, the produced handoff, and cross-references. Iron Law in operational form, full process, Common Rationalisations, Red Flags, and (for fieldtest) the spec template now live solely in the agent file. Net −160 LOC across the skills tree. CLAUDE.md pointer for 'Bug fixes — TDD, always' updated to reflect that the substantive discipline lives in the agent file, not the skill file.
3.3 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 is committed. 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 in AILang 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
→ RED test → handoff, plus the Phase 4.5 architecture-question trigger
after three failed hypotheses — lives in
agents/ailang-debugger.md. 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
cargo test(any crate) - wrong stdout from
ail run <example> - a segfault from a built binary
- a panic in the compiler
- a structured diagnostic from
ailang-bencherorailang-architectthat 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. The second was formerly the CLAUDE.md "Bug fixes — TDD, always" section before the 2026-05-09 skill-system migration.
Dispatch
Dispatch ailang-debugger with:
| Carrier field | Content |
|---|---|
symptom |
Exact error message, stack trace, wrong output, or repro command |
repro_known |
One-line repro if known, otherwise the agent finds one |
recent_iter |
Iteration that last touched the suspected area (often git log tail) |
The agent commits the RED test as test: red for <symptom> and reports
the handoff carrier for implement mini-mode. The agent does NOT write
the fix — splitting RED (this skill) and GREEN (implement mini-mode)
across two dispatches keeps the diagnosis honest.
Handoff Contract
debug produces, for implement mini-mode:
| Field | Content |
|---|---|
red_test_path |
absolute path to the failing test file |
cause_summary |
1-2 sentences naming the file + function + why |
constraint |
"minimal fix, no surrounding cleanup" |
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:
skills/debug/agents/ailang-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:
skills/implement/SKILL.md— runs the GREEN side after the RED test is committed. - Project source: former CLAUDE.md "Bug fixes — TDD, always" section is now superseded by this file; CLAUDE.md keeps a one-line pointer.