Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: single-source the debug carrier and handoff contracts

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Brummel
2026-05-30 10:26:06 +02:00
parent 35417b491e
commit de42974056
2 changed files with 24 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
debug/SKILL.md
+15 -16
View File
@@ -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
debug/agents/debugger.md
+9 -3
View File
@@ -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.