Files

T

Brummel 7715ab44f3 debug: skill + debugger agent migrated

Second skill migrated using the boss pattern. Purely a discipline
skill (RED-first bug fixing); no AILang-specific contracts.

Vocabulary substitutions:
- AILang → "this project" / "the project"
- "ailang-debugger" / "ailang-bencher" / "ailang-architect"
  → "debugger" / "bencher" / "architect" (ailang- prefix dropped)
- "Boss" → "orchestrator"

AILang-specific bits replaced with profile slots:
- `cargo build` / `cargo test` → `commands.build` / `commands.test`
- `ail emit-ir`, `ail run`, `ail build` → "the project's run command"
  (generic — these were AILang CLI specifics)
- `crates/ail/tests/e2e.rs` hardcoded test path → "the testing
  location idiomatic for this project"
- `design/INDEX.md` → `paths.design_ledger` (optional; if the
  project does not have one configured, that step short-circuits)

Universal substance preserved verbatim:
- Iron Law (3 lines)
- Four phases + Phase 4.5 (the three-failures-means-architecture
  rule)
- Status protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT /
  BLOCKED)
- All 7 Common Rationalisations rows
- All 8 Red Flags bullets

Dropped from original:
- "former CLAUDE.md 'Bug fixes — TDD, always' section before the
  2026-05-09 skill-system migration" — AILang history, not
  load-bearing for the discipline
- "for the AILang project at /home/brummel/dev/ailang" — AILang
  identity, replaced with generic "this project"

Cross-refs (post-flatten):
- `../implement/SKILL.md` for the GREEN handoff target
- `agents/debugger.md` from the skill body

2026-05-28 15:54:21 +02:00

3.7 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 → RED test → handoff, plus the Phase 4.5 architecture- question trigger after three failed hypotheses — lives in agents/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 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 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 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:

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

3.7 KiB Raw Blame History