docs: close the glossary recall gap, and name the cheap-refutation criterion - #1386
docs: close the glossary recall gap, and name the cheap-refutation criterion#1386ms2sato wants to merge 1 commit into
Conversation
…iterion Two rule additions from one retrospective. Gap-Scan gains a one-line recall point for glossary triggers. Of the three layers that could catch a missing entry -- AC drafting, this checklist, acceptance-check Q9 -- only Q9 was, because the checklist had no entry at all. The judgment stays in glossary-maintenance.md, whose orthogonality clause is clarified to forbid duplicating the substance rather than pointing at it, so nobody later 'restores' it by deleting the pointer. workflow.md gains a sister criterion to Inference vs Verification: price the refutation of a universal claim before accepting it. Different axis -- that rule asks which signal is ground truth, this one asks what shape the claim has, whoever made it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Important Review skippedIgnore keyword(s) in the title. ⛔ Ignored keywords (1)
Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Test Coverage CheckNo production files matching coverage patterns were changed. Rule/Skill Duplication Check✅ No rule paragraphs found verbatim in any skill file. Language Check (public artifacts)✅ All public artifacts use Latin / Greek / Cyrillic scripts only. Source-Comment Blame-Shift Check✅ No new Issue / PR / dated CodeRabbit references in source comments. |
1 participant
Two rule additions from the PR #1384 retrospective. Both were routed to the Architect first, because each touches something the Orchestrator should not change alone: the first modifies a written design decision, the second places a new axis in the rule system.
1. Gap-Scan gains a glossary recall point (Q1.7)
Two PRs in two days — #1373 and #1384 — reached the Orchestrator's acceptance check with the
docs/glossary.mdentry missing, and Q9 caught both.The #1384 delegate's retrospective named the mechanism exactly, and it is worth quoting because it rules out the obvious explanation:
So this is not "the author didn't know the rule". Three layers could catch a missing entry — AC drafting, this checklist, acceptance-check Q9 — and only the last one was, because this checklist had no entry at all. A PR that adds a type, a table, and three endpoints is squarely in Gap-Scan's stated scope; the rule it needed to recall was simply never named there.
The judgment stays where it was. Q1.7 is one line that sends the reader to
glossary-maintenance.md; the trigger list and the drift-handling tree are not reproduced. That distinction is load-bearing — see below.2.
glossary-maintenance.md's orthogonality clause is clarifiedThat file said Gap-Scan "does not include glossary checks", which reads as forbidding exactly what Q1.7 does. The Architect re-derived the clause's intent from its context: it exists so that Gap-Scan does not absorb the judgment — the glossary rule is a separate mechanical gate precisely because LLM self-review is weak at terminology drift, and dissolving that into Gap-Scan would duplicate the responsibility.
A pointer is not the judgment. The clause now says so, and records why the pointer was added, so a later reader does not "restore" the orthogonality by deleting it.
3.
workflow.mdgains a sister criterion: price the refutation of a universal claimPlaced next to Inference vs Verification rather than inside it, because it is a different axis. That rule asks which signal you are treating as ground truth. This one asks what shape the claim has, regardless of who made it:
The asymmetry is the point. Refuting costs one command; accepting a false universal costs everything built on it, because a universal is what people stop searching after.
Two occurrences on 2026-08-20, and the second is the Orchestrator's own:
lsrefuted it; the precedent existed and the coverage gap was real.queryFnsignature trap was silently affecting 18 sibling call sites and framed it to the owner as probable latent debt. A delegate measured it in two minutes:typecheckcatches it at every site.Both were plausible, both were refutable in under a minute, and only one was checked before it travelled.
Boundary, written into the rule: this is not "distrust universal claims", it is "price the refutation". "This distributed system never deadlocks" is not settled by a grep and needs its own verification. The criterion fires only where a counterexample search is cheap.
The Architect's argument for landing it despite the two examples sharing a day: it is not a new heuristic but a name for a point several existing disciplines already circle — the vacuous truth of
[].every()in boundary-value testing, and the way an "accepted risk" paragraph can quietly remove something from the verification surface. Same shape each time: a universal, an empty set, or a negation, cheap to state and expensive to have wrong.Test plan
Documentation only — no production code, no test changes.
bun run check:lang— clean (121 files scanned)node .claude/skills/orchestrator/preflight-check.js— clean. The Rule/Skill Duplication Check is the relevant one here and passes: Q1.7 points at the glossary rule rather than reproducing it.