Skip to content

docs(standards): fix the class, not the instance — canon rule + PR-template check (backend#1680) - #224

Merged
LukasWodka merged 1 commit into
developfrom
feat/1680-fix-the-class
Aug 11, 2026
Merged

docs(standards): fix the class, not the instance — canon rule + PR-template check (backend#1680)#224
LukasWodka merged 1 commit into
developfrom
feat/1680-fix-the-class

Conversation

@LukasWodka

@LukasWodkaLukasWodka commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

What

Encodes the defect pattern from today's handoff, in two places: the canon (org-standards.md, syncs fleet-wide) and the PR template (produces an artifact).

The pattern

Four instances on 2026-08-11, in two shapes — and a rule aimed only at "neighbouring bugs" catches half:

instanceshape
discover() left bare beside a wrapped load()other call site
epoch helper used at 2 sites, a 3rd did it inlineother call site
hooksPath guard canonicalised dirname not the path → .. escaped itother input to the same guard
hook probed make but not the venv toolchain it callsother input to the same guard

Why the checklist line, not just the canon line

A prose rule produces nothing a reviewer can look for. The template line produces an artifact whose absence is visible:

Sibling check — what class is this bug in, and how did you cover it? (paste the grep, or "N/A — one-off")

And the argument for making it mechanical is empirical: the stuck-run detector built from today's lessons reproduced the very same mistake — it encoded the symptom (runner=NONE) rather than the condition (nothing progressing), and would have cancelled a healthy production deploy. The pattern survives being named.

Cost, stated up front

Editing the canon drifts all 19 repos and needs a sync fan-out. This is the third canon edit this week, and it is exactly the treadmill worth a decision (auto-merge on green, or batching) rather than paying again — tracked on backend#1680.

Test plan

  • standards-sync selftest: 27 checks, 0 failed
  • report run: the block still splices cleanly against all 19 targets (19 drifted is the expected fan-out, not a defect)

Parent epic: backend#1680.


Note

Low Risk
Documentation and PR-template only; no product code, auth, or data paths. Canon edits trigger expected fleet CLAUDE.md drift until standards-sync PRs land.

Overview
Documents the “fix the class, not the instance” defect pattern in the fleet canon (org-standards.md Quality bar): before shipping a bug fix, name the class and sweep other call sites (grep the symbol) and other inputs to the same guard (what else hits that branch); if the class can’t be enumerated cheaply, say so in the PR.

Adds a matching Sibling check line at the top of the PR template checklist so reviewers get a concrete artifact (grep output or “N/A — one-off”) instead of relying on prose alone.

No runtime or application code changes; merging the canon edit will fan out via standards-sync to consuming repos’ CLAUDE.md blocks as usual.

Reviewed by Cursor Bugbot for commit 59f76af. Bugbot is set up for automated code reviews on this repo. Configure here.

…mplate check (backend#1680)
Four instances on 2026-08-11, in TWO shapes -- and a rule aimed only at
"neighbouring bugs" catches half of them:
other CALL SITES
* discover() left bare beside a wrapped load()
* an epoch helper used at 2 sites while a 3rd did it inline
other INPUTS TO THE SAME GUARD
* the hooksPath guard canonicalised dirname, not the path, so `..` escaped it
* the pre-push hook probed `make` but not the venv toolchain it calls
The canon line names both shapes. The PR-template line is the part that does the
work: it produces an artifact a reviewer can see is MISSING, where a prose rule
produces nothing to look for.
Why mechanical rather than remembered: the stuck-run detector built FROM today's
lessons reproduced the same mistake -- it encoded the symptom (runner=NONE)
instead of the condition (nothing progressing), and would have cancelled a
healthy production deploy. The pattern survives being named, which is the whole
argument for a checklist item over a paragraph.
Cost, stated rather than discovered: editing the canon drifts all 19 repos and
needs a sync fan-out. That is the third such edit this week and is exactly the
treadmill worth deciding about (auto-merge on green, or batching) -- tracked on
backend#1680.
Verified: standards-sync selftest 27 checks / 0 failed; the report still splices
the block cleanly against all 19 targets.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@LukasWodkaLukasWodka self-assigned this Aug 11, 2026
@LukasWodka
LukasWodka merged commit 6e133e6 into developAug 11, 2026
13 checks passed
LukasWodka added a commit that referenced this pull request Aug 12, 2026
#220 and #224 both landed the same rule one minute apart, so org-standards.md
carried two near-identical 'Fix the class, not the instance' bullets. Because
this file is the synced canon, the duplicate would propagate into every repo's
CLAUDE.md (Bugbot, on the develop->staging mirror #226, which it blocked).
Keeps the line-25 wording: the neighbouring bullets all use unbolded lead-ins,
and the removed one was the only bullet in the file starting with bold. It also
sat between the post-PR and recurring-finding bullets, splitting that flow.
Verified: one occurrence of the rule remains, zero bullets start with bold.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
@LukasWodka
LukasWodka deleted the feat/1680-fix-the-class branch August 14, 2026 13:53
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@LukasWodka