From de42974056f7a3502a1268553f8bc52788c4f73e Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 30 May 2026 10:26:06 +0200 Subject: [PATCH] refactor: single-source the debug carrier and handoff contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The carrier (symptom/repro_known/recent_iter) and handoff (red_test_path/cause_summary/constraint) field definitions were tabled in full in both SKILL.md and debugger.md — the exact duplication that let the `constraint` wording drift earlier. Since the debugger agent runs in a fresh context, it must carry both contracts inline regardless; that makes debugger.md the natural single source. Mark its Carrier-contract and Output-format tables authoritative, fold in the richer field descriptions that only SKILL.md had, and reduce SKILL.md to naming the fields plus a pointer — no field semantics restated. Drift-prone prose now lives in exactly one place. Consistent with SKILL.md's own stated split (debugger.md = source of truth; skill = trigger/dispatch/handoff). Co-Authored-By: Claude Opus 4.8 (1M context) --- debug/SKILL.md | 31 +++++++++++++++---------------- debug/agents/debugger.md | 12 +++++++++--- 2 files changed, 24 insertions(+), 19 deletions(-) diff --git a/debug/SKILL.md b/debug/SKILL.md index bddc15b..2dce51c 100644 --- a/debug/SKILL.md +++ b/debug/SKILL.md @@ -51,13 +51,11 @@ 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) | +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 @@ -75,13 +73,11 @@ 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 — minimal and autonomous (Phase 3) | -| `cause_summary` | 1-2 sentences naming the file + function + why | -| `constraint` | `"minimal fix, no surrounding cleanup, no opportunistic refactor"` | +`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 @@ -91,8 +87,11 @@ separate one. - **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. + Common Rationalisations table, and the Red Flags list. It is + also the single source for the carrier and handoff field + definitions (Carrier contract / Output format); this skill + names the fields but does not redefine them. 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 diff --git a/debug/agents/debugger.md b/debug/agents/debugger.md index d0c7b05..0c7e44d 100644 --- a/debug/agents/debugger.md +++ b/debug/agents/debugger.md @@ -41,6 +41,9 @@ the dispatching skill file does not duplicate it. ## Carrier contract — what the controller hands you +This table is the authoritative definition of the carrier fields; +the dispatching skill references it rather than restating it. + | Field | Content | |-------|---------| | `symptom` | Exact error message, stack trace, wrong output, or repro command | @@ -203,9 +206,12 @@ At most 250 words, structured: - **Cause:** file + function + why (1-2 sentences). - **RED test:** path to the new test in the working tree (uncommitted). -- **Handoff carrier for `implement` mini-mode:** - - `red_test_path`: absolute path - - `cause_summary`: 1-2 sentences +- **Handoff carrier for `implement` mini-mode** (this list is + the authoritative definition of the handoff fields; the + dispatching skill references it rather than restating it): + - `red_test_path`: absolute path to the failing test file — + minimal and autonomous (Phase 3) + - `cause_summary`: 1-2 sentences naming the file + function + why - `constraint`: `"minimal fix, no surrounding cleanup, no opportunistic refactor"` - **Concerns / blockers:** if applicable.