iter disc.1: boss-only commits + main-as-quarantine (no branches in implement)
Two project-wide rules are now explicit across every skill: 1. Only the Boss commits. No skill agent (implementer, brainstormer, planner, debugger, fieldtester, docwriter, architect, bencher) runs `git commit`. Agents write their artefacts to the working tree as unstaged changes; the Boss inspects, decides commit shape, and commits. 2. main HEAD is sacrosanct. No actor runs `git reset` or `git revert` on main. Bad work stays in the working tree where it is still discardable via `git checkout -- <paths>`. Implement loses the `iter/<iter_id>` branch mechanic entirely; Phase 0 of the orchestrator-agent now does a clean-tree check and refuses to start on a dirty tree. Per-task agent commits are removed everywhere; reviewers operate against `git diff HEAD` instead of `pre_task_sha..head_sha`. Motivation: 2026-05-11 iter 23.4 stranded prep2/prep3 commits on an iter-branch that never integrated to main, then a corrected spec falsely claimed those commits had shipped. Branch-per-iter + manual-Boss-merge + iter-stacking made the strand structurally possible. See docs/journals/2026-05-11-iter-disc.1.md for the full per-task notes and motivation.
This commit is contained in:
+14
-6
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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.
|
||||
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 exists in the working tree. Mandatory for any bug, including ones that look trivial.
|
||||
---
|
||||
|
||||
# debug — RED-first bug diagnoser
|
||||
@@ -57,10 +57,17 @@ Dispatch `ailang-debugger` with:
|
||||
| `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.
|
||||
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 Boss 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 Boss commits the
|
||||
RED test first; for a streamlined-fix flow the Boss commits the
|
||||
combined RED+GREEN at the end of mini-mode).
|
||||
|
||||
## Handoff Contract
|
||||
|
||||
@@ -82,7 +89,8 @@ scope for the bug-fix iteration and gets queued for a separate one.
|
||||
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.
|
||||
side after the Boss has decided whether to commit the RED test
|
||||
separately or as part of the final fix commit.
|
||||
- **Project source:** former CLAUDE.md "Bug fixes — TDD, always"
|
||||
section is now superseded by this file; CLAUDE.md keeps a one-line
|
||||
pointer.
|
||||
|
||||
@@ -14,11 +14,14 @@ segfault, wrong stdout, panic, observable misbehaviour.
|
||||
|
||||
## What this role is for
|
||||
|
||||
Bug diagnosis is RED-first. Your output is a *committed failing test* plus a
|
||||
1-2 sentence cause summary. The fix itself is `skills/implement`'s job, run
|
||||
in mini-mode. Splitting RED and GREEN across two dispatches keeps the
|
||||
diagnosis honest: the test is written before any fix is attempted, so it
|
||||
genuinely captures the symptom, not the post-fix code path.
|
||||
Bug diagnosis is RED-first. Your output is a *failing test in the working
|
||||
tree* (uncommitted) plus a 1-2 sentence cause summary. The fix itself is
|
||||
`skills/implement`'s job, run in mini-mode. You never commit anything;
|
||||
the Boss decides whether to commit the RED test separately as an audit-
|
||||
trail commit or to roll it into the final fix commit. Splitting RED
|
||||
and GREEN across two dispatches keeps the diagnosis honest: the test
|
||||
is written before any fix is attempted, so it genuinely captures the
|
||||
symptom, not the post-fix code path.
|
||||
|
||||
## Standing reading list
|
||||
|
||||
@@ -94,8 +97,10 @@ Each phase completes before the next starts.
|
||||
- automated, deterministic — same input always same output
|
||||
- doc comment names the *property* the test protects, not the symptom
|
||||
3. Run the test. Confirm it fails with the symptom the carrier described.
|
||||
4. Commit the failing test as a separate commit:
|
||||
`git commit -m "test: red for <symptom>"`.
|
||||
4. Leave the failing test in the working tree as an unstaged change.
|
||||
You do NOT commit. The Boss decides commit shape; the suggested
|
||||
subject if the Boss elects to commit the RED separately is
|
||||
`test: red for <symptom>`.
|
||||
|
||||
### Phase 4 — Hand off
|
||||
|
||||
@@ -120,9 +125,10 @@ orchestrator escalates.
|
||||
|
||||
End every report with exactly one of:
|
||||
|
||||
- `DONE` — RED test committed, cause documented, ready for `implement`
|
||||
mini-mode. Provide the handoff carrier (see Output format).
|
||||
- `DONE_WITH_CONCERNS` — RED test committed, but during diagnosis you
|
||||
- `DONE` — RED test in the working tree (uncommitted), cause documented,
|
||||
ready for `implement` mini-mode. Provide the handoff carrier (see
|
||||
Output format).
|
||||
- `DONE_WITH_CONCERNS` — RED test in the working tree, but during diagnosis you
|
||||
noticed a related issue the orchestrator should know about (e.g. another
|
||||
test would also fail under this code path; the bug shipped in iteration N
|
||||
but the JOURNAL entry didn't flag the risk).
|
||||
@@ -140,7 +146,7 @@ At most 250 words, structured:
|
||||
- **Symptom:** exact error / wrong output (verbatim).
|
||||
- **Repro:** the one-line command.
|
||||
- **Cause:** file + function + why (1-2 sentences).
|
||||
- **RED test:** path to the new test + commit SHA.
|
||||
- **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
|
||||
@@ -164,7 +170,7 @@ At most 250 words, structured:
|
||||
| "I'll write the fix and the test together" | Test-after proves nothing about whether the test would have caught the pre-fix bug. RED before GREEN — always. |
|
||||
| "The cause is obviously the new tag-extract emit" | Confident guesses paper over real causes. Phase 1 is data-flow tracing, not guessing. |
|
||||
| "Two RED tests both mis-pinned the symptom; third try is the right one" | Two failures means the hypothesis space is wrong. Phase 4.5 fires now, not after the third try. |
|
||||
| "End-of-day, just commit a fix and write the test tomorrow" | End-of-day pressure is the worst time for shotgun fixes. Clean tree + open bug > three speculative half-fixes. |
|
||||
| "End-of-day, just drop a fix into the working tree and write the test tomorrow" | End-of-day pressure is the worst time for shotgun fixes. Clean tree + open bug > three speculative half-fixes. Diagnosis is RED-first; the fix is a separate dispatch. |
|
||||
| "This bug is trivial, the existing tests will catch regressions" | The existing tests already passed while this bug shipped. By definition they don't cover it. |
|
||||
| "I can fix and verify in one go and be done" | The skill explicitly splits RED (you) and GREEN (`implement` mini-mode). Don't collapse them; the split is the whole point. |
|
||||
|
||||
@@ -177,4 +183,4 @@ At most 250 words, structured:
|
||||
- "Pattern says X but I'll adapt it differently"
|
||||
- *"One more hypothesis"* (when ≥ 2 already failed)
|
||||
- About to apply ANY edit outside the new test file
|
||||
- About to commit a fix in this dispatch
|
||||
- About to run `git commit` (anywhere, ever — you never commit)
|
||||
|
||||
Reference in New Issue
Block a user