Brummel
51da9fab53
Two project-wide rules are now explicit across every skill: 1. Only the Boss commits. No skill agent (implementer, brainstormer, planner, debugger, fieldtester, docwriter, architect, bencher) runs `git commit`. Agents write their artefacts to the working tree as unstaged changes; the Boss inspects, decides commit shape, and commits. 2. main HEAD is sacrosanct. No actor runs `git reset` or `git revert` on main. Bad work stays in the working tree where it is still discardable via `git checkout -- <paths>`. Implement loses the `iter/<iter_id>` branch mechanic entirely; Phase 0 of the orchestrator-agent now does a clean-tree check and refuses to start on a dirty tree. Per-task agent commits are removed everywhere; reviewers operate against `git diff HEAD` instead of `pre_task_sha..head_sha`. Motivation: 2026-05-11 iter 23.4 stranded prep2/prep3 commits on an iter-branch that never integrated to main, then a corrected spec falsely claimed those commits had shipped. Branch-per-iter + manual-Boss-merge + iter-stacking made the strand structurally possible. See docs/journals/2026-05-11-iter-disc.1.md for the full per-task notes and motivation.
3.9 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 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 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 Boss 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 Boss commits the
RED test first; for a streamlined-fix flow the Boss commits the
combined RED+GREEN at the end of mini-mode).
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 Boss has decided whether to commit the RED test separately or as part of the final fix commit. - Project source: former CLAUDE.md "Bug fixes — TDD, always" section is now superseded by this file; CLAUDE.md keeps a one-line pointer.