Skip to content

docs(standards): fix the class, not the instance - #220

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

docs(standards): fix the class, not the instance#220
LukasWodka merged 1 commit into
developfrom
docs/1646-fix-the-class

Conversation

@LukasWodka

@LukasWodkaLukasWodka commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds one rule to the Quality bar in org-standards.md:

Fix the class, not the instance. The bug you just fixed is a member of a class; check the rest of the class before you push. Two shapes, and aiming at only the first catches half of them: other call sites — grep the symbol or pattern you changed — and other inputs to the same guard — what else reaches this branch? If the class can't be cheaply enumerated, say so in the PR rather than leaving it implied that you covered it.

Why now

Four defects in a single day shared exactly one root cause — a fix that addressed the instance in front of the author and left the rest of its class:

#defectshape
1a guard wrapped around load(checkout) while discover(root) stayed bareother call site
2an epoch-completeness helper used at 2 sites while a 3rd did it inline with a raw non-distinct .count()other call site
3a core.hooksPath guard that canonicalised the dirname of the path, not the path — so core.hooksPath=.. escapes itother input, single site
4a pre-push hook that probed for make but not for the ruff/pytest toolchain it then callsother input, single site

Naming both shapes is the point. 1 and 2 are findable by grepping what you changed. 3 and 4 are single-site — a different input reaches the same guard, and no grep of the symbol will ever show you that. A rule phrased only as "check the code nearby" catches half the class, which is precisely how 3 and 4 shipped.

Corroboration from the other direction the same week: a fleet-wide verification script accumulated five defects of this kind, and every one surfaced by running it across all 16 repos rather than by reading the diff (release-train#48). Reviewing a predicate is not the same as enumerating what reaches it.

Scope

Canon only — one line in org-standards.md. The sync (backend#1602) will report the fleet DRIFTED and can open the per-repo CLAUDE.md PRs; per-repo copies are never hand-edited.

Deliberately not in this PR: a matching Sibling check: line in each repo's .github/pull_request_template.md. scripts/standards-sync.py syncs CLAUDE.md only, so templates would be 17 separate PRs — worth doing (a rule that produces an artifact beats one that relies on memory), but it is its own change, and possibly its own extension to the sync script. Filing separately.

Refs backend#1646

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only change to org engineering standards with no runtime, security, or data-handling impact.

Overview
Quality bar in org-standards.md gains a new bullet: fix the class, not the instance — after a bugfix, enumerate the rest of the same defect class before pushing.

The rule names two shapes reviewers should expect: other call sites (grep the symbol or pattern you changed) and other inputs to the same guard (what else can reach that branch). If the class can't be cheaply enumerated, the PR should say so explicitly instead of implying full coverage.

Canon-only; fleet CLAUDE.md copies follow via the existing standards sync (not edited in this PR).

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

Four defects in one day shared a root cause: a fix that addressed the instance in
front of the author and left the rest of its class behind.
1. a guard wrapped around load(checkout) while discover(root) stayed bare
2. an epoch-completeness helper used at two sites while a third did it inline
with a raw non-distinct .count()
3. a core.hooksPath guard that canonicalised the DIRNAME of the path, not the
path, so core.hooksPath=.. escapes it
4. a pre-push hook that probed for make but not for the ruff/pytest toolchain
it then calls
The rule names both shapes deliberately. 1 and 2 are other CALL SITES -- findable
by grepping what you changed. 3 and 4 are single-site: another INPUT reaches the
same guard, and no grep of the symbol will show you that. A rule that only says to
check the code nearby catches half the class, which is how 3 and 4 shipped.
Same week, from the other direction: a fleet-wide verification script accumulated
five defects of exactly this kind, and every one surfaced by RUNNING it across all
16 repos rather than by reading the diff (tracebloc/release-train#48). Reviewing a
predicate is not the same as enumerating what reaches it.
Canon only. The sync (backend#1602) will report the fleet DRIFTED and can open the
CLAUDE.md PRs; per-repo copies are never edited by hand.
Refs backend#1646
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@LukasWodkaLukasWodka self-assigned this Aug 11, 2026
@LukasWodka
LukasWodka merged commit 8658260 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 docs/1646-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