From cea3dc3c1ee458a75e68afb0f29f9e975084752b Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Mon, 17 Aug 2026 14:53:32 -0700 Subject: [PATCH] fix(skills): state the paperwork boundary in prose, not template notation (#2755) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The triage rule 'A finding whose fix edits {spec_file}: dismiss' gets quoted verbatim into Review Triage Logs, leaking the unresolved placeholder into story specs (observed in three consecutive unattended runs). Name the file by its role instead — 'the spec this build is implementing' / 'the spec under review' — so quoting the rule is harmless, mark the defer clause's other-spec distinction explicit, and make its document list read as examples (e.g.), not an enumeration. --- src/bmm-skills/ship/bmad-build-auto/step-04-review.md | 2 +- src/bmm-skills/ship/bmad-build/step-04-review.md | 2 +- src/bmm-skills/ship/bmad-build/step-oneshot.md | 2 +- src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/bmm-skills/ship/bmad-build-auto/step-04-review.md b/src/bmm-skills/ship/bmad-build-auto/step-04-review.md index 043c54d11..e4cd8e10f 100644 --- a/src/bmm-skills/ship/bmad-build-auto/step-04-review.md +++ b/src/bmm-skills/ship/bmad-build-auto/step-04-review.md @@ -36,7 +36,7 @@ Announce skipped layers first, then launch every active layer before handling an - `high`: intolerable - **Keep or dismiss.** Keep a finding only where verification confirmed its consequence. Dismiss noise, claims the verification refuted, and claims it could not substantiate — no path to the claimed consequence at the named site is a valid disposal. Whatever the reason, it must dispose of the finding's own claim: a true fact about neighboring code that leaves the claim standing is not a dismissal, and the finding stays kept. Record each dismissal with its reason in the triage log below; never drop a finding silently. - Scope authority: a finding may be dismissed or later deferred *as out of scope* only on the authority of the intent itself. The spec's scope language, the plan, and the diff's own shape are not admissible scope authorities — if only they exclude a finding, treat it as evidence against the chosen reading (intent_gap or bad_spec), not as out of scope. - - A finding whose fix edits `{spec_file}`: dismiss. A finding whose fix edits an agent-context document (CLAUDE.md, AGENTS.md, rules files, specs): defer, never patch. + - A finding whose fix edits the spec this build is implementing: dismiss. A finding whose fix edits an agent-context document (e.g. CLAUDE.md, AGENTS.md, rules files, other specs): defer, never patch. 2. Group the survivors by shared root cause — two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence and the highest severity among them. 3. Route each entry into exactly one triage category. The first three are **this story's problem** — caused or exposed by the current change. The last is **not this story's problem**. - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. diff --git a/src/bmm-skills/ship/bmad-build/step-04-review.md b/src/bmm-skills/ship/bmad-build/step-04-review.md index 76495f7e0..5f92199df 100644 --- a/src/bmm-skills/ship/bmad-build/step-04-review.md +++ b/src/bmm-skills/ship/bmad-build/step-04-review.md @@ -35,7 +35,7 @@ If a layer's instruction requires subagents and none are available, for each suc - `medium`: tolerable - `high`: intolerable - **Keep or dismiss.** Keep a finding only where verification confirmed its consequence. Dismiss noise, claims the verification refuted, and claims it could not substantiate — no path to the claimed consequence at the named site is a valid disposal. Whatever the reason, it must dispose of the finding's own claim: a true fact about neighboring code that leaves the claim standing is not a dismissal, and the finding stays kept. Record each dismissal with its reason in the `## Review Triage Log` section of `{spec_file}`; never drop a finding silently. - - A finding whose fix edits `{spec_file}`: dismiss. A finding whose fix edits an agent-context document (CLAUDE.md, AGENTS.md, rules files, specs): defer, never patch. + - A finding whose fix edits the spec this build is implementing: dismiss. A finding whose fix edits an agent-context document (e.g. CLAUDE.md, AGENTS.md, rules files, other specs): defer, never patch. 2. Group the survivors by shared root cause — two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence and the highest severity among them. 3. Route each entry into exactly one triage category. The first three are **this story's problem** — caused or exposed by the current change. The last is **not this story's problem**. - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. diff --git a/src/bmm-skills/ship/bmad-build/step-oneshot.md b/src/bmm-skills/ship/bmad-build/step-oneshot.md index 5484de236..3928cec5a 100644 --- a/src/bmm-skills/ship/bmad-build/step-oneshot.md +++ b/src/bmm-skills/ship/bmad-build/step-oneshot.md @@ -30,7 +30,7 @@ Once every layer has reported — and not before — render a verdict on each fi - **Verify its own claimed consequence** at the location it names. Read past the changed lines — into the callers, the guards upstream, whatever else the site depends on — far enough to tell whether that consequence actually occurs. Another finding's outcome, however adjacent, never settles this one. - **Assign severity** from the verified consequence for the software's user: `low` (none or cosmetic), `medium` (tolerable), `high` (intolerable). - **Keep or dismiss.** Keep a finding only where verification confirmed its consequence. Dismiss noise, claims the verification refuted, and claims it could not substantiate — no path to the claimed consequence at the named site is a valid disposal. Whatever the reason, it must dispose of the finding's own claim: a true fact about neighboring code that leaves the claim standing is not a dismissal, and the finding stays kept. Record each dismissal with its reason; never drop a finding silently. -- A finding whose fix edits an agent-context document (CLAUDE.md, AGENTS.md, rules files, specs): defer, never patch. +- A finding whose fix edits an agent-context document (e.g. CLAUDE.md, AGENTS.md, rules files, specs): defer, never patch. Group the survivors by shared root cause — two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence and the highest severity among them. Then route each entry in this order: diff --git a/src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md b/src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md index 3b3d4b628..54e6f64df 100644 --- a/src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md +++ b/src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md @@ -23,7 +23,7 @@ - `medium` -- tolerable - `high` -- intolerable - **Keep or dismiss.** Keep a finding only where verification confirmed its consequence. Dismiss noise, claims the verification refuted, and claims it could not substantiate -- no path to the claimed consequence at the named site is a valid disposal. Whatever the reason, it must dispose of the finding's own claim: a true fact about neighboring code that leaves the claim standing is not a dismissal, and the finding stays kept. Record each dismissal with its reason for the summary; never drop a finding silently. - - A finding whose fix edits `{spec_file}`: dismiss. A finding whose fix edits an agent-context document (CLAUDE.md, AGENTS.md, rules files, specs): defer, never patch. + - A finding whose fix edits the spec under review: dismiss. A finding whose fix edits an agent-context document (e.g. CLAUDE.md, AGENTS.md, rules files, other specs): defer, never patch. 3. **Group the survivors by shared root cause** -- two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence in `detail` and the highest severity among them; set `source` to the contributing layers joined with `+` (e.g., `blind-hunter+edge-case-hunter`).