Summary
Two independent retrospectives (#617, #629) found the same defect: a hand-tallied count of matching items (e.g. "14-member OPA series", "26 templates change subCategory") written into a design doc's or issue's prose turned out to be off by one, because it was transcribed by eye from a list or grep result instead of being backed by the command that actually produced the number. Both times the mistake was caught only because a review subagent happened to independently recompute the count from real data before the PR merged — not by any gate.
#617 proposed a fix in prose ("any count claim in a spec/plan doc... should be computed by a one-line script and pasted as output, not hand-tallied") but never turned it into a tracked, actionable item, and the identical mistake recurred in #629 (~14 hours later). This issue exists so the fix doesn't get proposed a third time without being acted on.
Proposed fix
Add a rule to CLAUDE.local.md (same style/precedent as the existing "Release-archive preflight" rule, which was added after a specific recurring bug class): when a design doc, plan, GitHub issue, or PR body states a specific count of matching items (template counts, allow-list membership, rail counts, etc.), the count must be accompanied by the exact command whose output produced it — either inline near the claim or in a verification/methodology section — rather than hand-tallied from a manually-read list. This is intentionally a documented convention, not a new automated parser/CI check: parsing arbitrary prose for count claims and re-verifying them automatically would be a disproportionate, bespoke NLP-ish effort for what is fundamentally a "cite your evidence" authoring habit — consistent with this repo's existing practice of pasting real command output as verification evidence elsewhere (design docs already do this for test results; this extends the same habit to narrative counts).
Acceptance criteria
Refs #617, #629, #501.
Summary
Two independent retrospectives (#617, #629) found the same defect: a hand-tallied count of matching items (e.g. "14-member OPA series", "26 templates change subCategory") written into a design doc's or issue's prose turned out to be off by one, because it was transcribed by eye from a list or
grepresult instead of being backed by the command that actually produced the number. Both times the mistake was caught only because a review subagent happened to independently recompute the count from real data before the PR merged — not by any gate.#617 proposed a fix in prose ("any count claim in a spec/plan doc... should be computed by a one-line script and pasted as output, not hand-tallied") but never turned it into a tracked, actionable item, and the identical mistake recurred in #629 (~14 hours later). This issue exists so the fix doesn't get proposed a third time without being acted on.
Proposed fix
Add a rule to
CLAUDE.local.md(same style/precedent as the existing "Release-archive preflight" rule, which was added after a specific recurring bug class): when a design doc, plan, GitHub issue, or PR body states a specific count of matching items (template counts, allow-list membership, rail counts, etc.), the count must be accompanied by the exact command whose output produced it — either inline near the claim or in a verification/methodology section — rather than hand-tallied from a manually-read list. This is intentionally a documented convention, not a new automated parser/CI check: parsing arbitrary prose for count claims and re-verifying them automatically would be a disproportionate, bespoke NLP-ish effort for what is fundamentally a "cite your evidence" authoring habit — consistent with this repo's existing practice of pasting real command output as verification evidence elsewhere (design docs already do this for test results; this extends the same habit to narrative counts).Acceptance criteria
CLAUDE.local.mdgets a new short rule (a few sentences, matching the existing rules' length/style) stating the convention above, with a reference to Retrospective: PR #616 (middleware category consolidation) merge review #617/Retrospective: PR #628 (server コンテナ rail consolidation) merge review #629 as the bug class it prevents (same citation style as the release-archive-preflight rule's "Refs Retrospective: superpowers drift detection (#390, PR #391) #392, Local deterministic gates: pinned actionlint/shellcheck provisioning and release-archive preflight (retro #392) #393").Refs #617, #629, #501.