The third issue on one surface names a failure class
Each bug fixed alone adds one specification for one symptom. When the same
surface (one screen, endpoint, command, query, workflow, module or rule
area) breaks a third time, the instances share a cause that no specification
owns yet, and the fourth instance is already on its way. Stop fixing instances:
name the failure class, give it an owning gate, then fix the instance.
Count first
Before fixing an issue, count the earlier ones on its surface:
gh issue list --state all --search "<surface> in:title,body" --limit 50
git log --oneline -- <paths of the surface>
Count bugs, regressions, reverts and review findings, open or closed. Fewer
than three: fix the instance with a regression specification. Three or more:
follow the steps below before writing the fix.
Steps
- Name the failure class in one sentence that states the property being
violated, not the symptom. Each earlier issue must be an instance of it, and
a reader must be able to recognize the next one by it. "Owner filter shows
archived items" is a symptom; "list filters are not exercised through the
rendered list by any test" is a class.
- Choose the owning gate by enforcement kind, preferring the earliest that
can catch the class: an analyzer (compile time), a lint rule, a CI check or
verification script, or one specification suite that covers every member of
the class (every filter, every endpoint), not one specification per bug. A
class that only judgment can catch gets a review checklist entry, and the
choice is stated as judgment-shaped; see the enforcement rule in
authoring-skills.md.
- Prove the gate fails on the current broken instance, or on the earlier
instances with their fixes reverted, before fixing anything. A gate that
passes on the broken code owns nothing; follow
guards-and-fuses.md so it cannot pass
vacuously.
- Register the class. When the repository keeps a failure-class table or
gate inventory, add one row: class, owning gate, where it runs. Otherwise
put the class name in the gate's failure message and the specification or
check name, so the next failure names its class.
- Fix the instance; the gate turns green. Run it with the repository's
normal gates, and make it a required CI check when it lives in CI.
- Close the loop. Link the earlier issues to the class in the pull request
comment, and leave a prose rule only for the judgment-shaped part.
Report
State the surface and the issues counted, the class sentence, the gate and
where it runs, that it failed before the fix and passes after, and anything
left judgment-shaped.
Pitfalls
- A fourth instance specification. Copying the third fix's specification
for the new symptom covers the symptom, not the class.
- A prose rule instead of a gate. Rules nobody enforces were already in
place for the earlier instances; text costs context and catches nothing.
- A class named after the symptom. If the next instance would not be
recognized by the sentence, the class is still too narrow.
- A gate that never ran red. Without the failing run, nothing shows it can
catch the class.
- A loose surface. Three unrelated bugs in one large module are not a
cluster; narrow the surface until the issues share a cause.
1---2name: cratis-engineering-regression-cluster3description: Use when a third regression hits the same surface, a fix keeps being reapplied or recurring failures need a shared cause. Not for isolated bugs, consolidation loss checks or false-success effect boundaries.4license: LICENSE5metadata:6 source: https://skillmd.com/skills/cratis/cratis-engineering-regression-cluster7---89# The third issue on one surface names a failure class1011Each bug fixed alone adds one specification for one symptom. When the same12**surface** (one screen, endpoint, command, query, workflow, module or rule13area) breaks a third time, the instances share a cause that no specification14owns yet, and the fourth instance is already on its way. Stop fixing instances:15name the **failure class**, give it an **owning gate**, then fix the instance.1617## Count first1819Before fixing an issue, count the earlier ones on its surface:2021```bash22gh issue list --state all --search "<surface> in:title,body" --limit 5023git log --oneline -- <paths of the surface>24```2526Count bugs, regressions, reverts and review findings, open or closed. Fewer27than three: fix the instance with a regression specification. Three or more:28follow the steps below before writing the fix.2930## Steps31321. **Name the failure class** in one sentence that states the property being33 violated, not the symptom. Each earlier issue must be an instance of it, and34 a reader must be able to recognize the next one by it. "Owner filter shows35 archived items" is a symptom; "list filters are not exercised through the36 rendered list by any test" is a class.372. **Choose the owning gate by enforcement kind**, preferring the earliest that38 can catch the class: an analyzer (compile time), a lint rule, a CI check or39 verification script, or one specification suite that covers every member of40 the class (every filter, every endpoint), not one specification per bug. A41 class that only judgment can catch gets a review checklist entry, and the42 choice is stated as judgment-shaped; see the enforcement rule in43 [authoring-skills.md](../../rules/authoring-skills.md).443. **Prove the gate fails** on the current broken instance, or on the earlier45 instances with their fixes reverted, before fixing anything. A gate that46 passes on the broken code owns nothing; follow47 [guards-and-fuses.md](../../rules/guards-and-fuses.md) so it cannot pass48 vacuously.494. **Register the class.** When the repository keeps a failure-class table or50 gate inventory, add one row: class, owning gate, where it runs. Otherwise51 put the class name in the gate's failure message and the specification or52 check name, so the next failure names its class.535. **Fix the instance**; the gate turns green. Run it with the repository's54 normal gates, and make it a required CI check when it lives in CI.556. **Close the loop.** Link the earlier issues to the class in the pull request56 comment, and leave a prose rule only for the judgment-shaped part.5758## Report5960State the surface and the issues counted, the class sentence, the gate and61where it runs, that it failed before the fix and passes after, and anything62left judgment-shaped.6364## Pitfalls6566- **A fourth instance specification.** Copying the third fix's specification67 for the new symptom covers the symptom, not the class.68- **A prose rule instead of a gate.** Rules nobody enforces were already in69 place for the earlier instances; text costs context and catches nothing.70- **A class named after the symptom.** If the next instance would not be71 recognized by the sentence, the class is still too narrow.72- **A gate that never ran red.** Without the failing run, nothing shows it can73 catch the class.74- **A loose surface.** Three unrelated bugs in one large module are not a75 cluster; narrow the surface until the issues share a cause.