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.
89 lines
3.3 KiB
Markdown
89 lines
3.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 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-bencher` or `ailang-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. 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.
|