Files

T

Brummel 7a58a530b1 feat(pipeline): route to the lightest correct methodology; move execution loops onto the Workflow substrate

The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.

Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
  a verification/enumeration axis ahead of the settled-vs-fork question.
  Each lighter arm carries a positive trigger matched by signature, not
  reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
  that propagates mechanically. Observe-then-bounce — make the edit,
  build, run the suite; clean build AND suite green unchanged commits;
  a hole bounces up (specify for a design choice, tdd for discovered
  test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
  mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
  mechanical/forwarding -> compiler-driven; encodes new behaviour ->
  tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
  not a heavy new skill ("the largest concrete win is small").

Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
  phase (implementer -> spec-compliance -> quality, + tester for E2E) is
  a separate top-level agent() call, so a single phase is independently
  invokable and inter-phase aggregation/re-loop is code. Retires the
  implement-orchestrator agent's inline-role-switch workaround (the four
  phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
  ~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
  only the autonomous/mechanical loops moved. try-and-error is deferred.

Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.

Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).

closes #7

2026-06-17 12:27:51 +02:00

4.3 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 → 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 (its CLAUDE.md project facts)
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.

debug is for a regression of existing behaviour. New test-specifiable behaviour is its sibling tdd's job (same two-stage RED→GREEN shape, triggered by a feature description rather than an observed misbehaviour) — route there instead.

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. The orchestrator does not execute these phases directly.
Hand-off target: ../implement/SKILL.md — runs the GREEN side as the implement-loop workflow in mode: "mini", after the orchestrator has decided whether to commit the RED test separately or as part of the final fix commit.
Sibling RED-first skill: ../tdd/SKILL.md — same two-stage RED→GREEN handoff to implement mini-mode, but triggered by a new test-specifiable behaviour rather than an observed bug.

4.3 KiB Raw Blame History