Mirror the shared Swift rules canon (rules-swift, commit 4ebb892) into docs/rules-swift/ as a read-only reference alongside the repo's tailored docs/rules/. PROVENANCE.md records the source, commit, and what was included or excluded; the upstream repo's own VCS, CI, and lint tooling is omitted as machinery rather than rule content. Exclude the vendored tree from the style gate (scripts/check-style.sh) and the pre-commit hook: the canon's enforcement docs quote the forbidden attribution phrases to define them, the same reason the repo's own enforcement files are already excluded.
156 lines
8.0 KiB
Markdown
156 lines
8.0 KiB
Markdown
# When a Correction Earns a Rule (MANDATORY)
|
|
|
|
**Status: MANDATORY whenever a correction, bug, or review note recurs.** A rule
|
|
set is only as good as its discipline about what enters it. Two failures are
|
|
symmetric and equally costly: leaving a recurring mistake uncodified, so it keeps
|
|
happening, and promoting a one-off into a permanent rule, so the set bloats with
|
|
noise that costs tokens every session and changes nothing. This rule sets the
|
|
thresholds: when a pattern has recurred enough to deserve a rule, and when it has
|
|
not. It is the upstream companion to `rules.md`, which governs *how* to write the
|
|
rule once this file says one is warranted.
|
|
|
|
## The core question
|
|
|
|
Before adding or updating a rule, answer: **has this corrected itself by being
|
|
told once, or does it keep coming back?** A rule is justified only by recurrence
|
|
or by stakes high enough that a single occurrence is one too many. A thing fixed
|
|
correctly the first time it was raised does not need a rule; it needs the fix.
|
|
|
|
## Thresholds for creating a rule
|
|
|
|
Treat these as the bar, not a ceiling. Meeting one is sufficient grounds to draft
|
|
a rule; meeting none means the correction stays a correction.
|
|
|
|
- **Recurring pattern (≥3 occurrences).** The same shape of code, the same kind of
|
|
fix, or the same structural choice appears across **three or more files or
|
|
sessions**. Three is the signal that it is a pattern and not a coincidence.
|
|
Extract it into a rule with a concrete example drawn from the real cases.
|
|
- **Repeated mistake (≥2 occurrences).** The same error or its near-twin is made,
|
|
caught, and corrected **twice**. The second time is the evidence that telling it
|
|
once did not stick; write the rule so the third time is caught by a check instead
|
|
of a person.
|
|
- **Repeated review note (≥3 mentions).** The same feedback is given in reviews
|
|
**three or more times**. Recurring human review effort is exactly the cost a rule
|
|
exists to eliminate; promote it.
|
|
- **Measured win (>20% on a real resource).** An optimization or approach that
|
|
saves more than a fifth of a measured resource (time, memory, tokens, build) on
|
|
a real workload, with the measurement recorded, earns a rule so the win is not
|
|
re-discovered each time.
|
|
|
|
## Stakes override the count
|
|
|
|
Some things get a rule on the **first** occurrence, because the cost of the second
|
|
is unacceptable. Recurrence is not required when:
|
|
|
|
- A **security or data-loss vulnerability** is discovered. One is enough.
|
|
- A change introduces a **breaking change with wide blast radius** (many files or
|
|
consumers affected). Codify the migration path immediately.
|
|
- A **new library, framework, or major dependency is adopted.** Its conventions
|
|
and gotchas become a rule at adoption, before the patterns scatter.
|
|
- A **compliance or correctness invariant** is introduced that must hold
|
|
everywhere. Make it a rule the moment it is known, not after it is first violated.
|
|
|
|
In these cases the threshold is one, and the rule is written the same session the
|
|
need is recognized.
|
|
|
|
## What does NOT earn a rule
|
|
|
|
The symmetric failure is over-codification. Resist a rule when:
|
|
|
|
- It happened **once** and the single correction resolved it, with no sign of
|
|
recurrence and no high-stakes reason to pre-empt a second.
|
|
- It is a **personal stylistic preference** with no defect behind it. Style with no
|
|
correctness or cost consequence is configuration, not a rule.
|
|
- It is **already covered** by an existing rule. The fix is to sharpen or
|
|
cross-reference that rule, not to add a second one that will drift out of sync
|
|
with the first.
|
|
- It is **so specific** that it will apply exactly once more, ever. A rule that
|
|
fires on a single future case is a comment in the wrong place.
|
|
|
|
When in doubt, record the correction (a note, a memory, a commit message) and wait
|
|
for the recurrence that promotes it. An uncodified note costs nothing; a premature
|
|
rule costs tokens every session it is loaded.
|
|
|
|
## Updating beats adding
|
|
|
|
The default when a pattern recurs near an existing rule is to **strengthen that
|
|
rule, not spawn a new one.** Adding overlapping rules splits the truth across two
|
|
files that will disagree the next time one is edited.
|
|
|
|
- **Better example found.** Replace the rule's example with the clearer real case.
|
|
- **New edge case discovered.** Add a clause or a note to the owning rule; do not
|
|
start a sibling.
|
|
- **Dependency or API changed.** Revise the affected rule in the same session the
|
|
change lands, so its examples and clauses do not go stale.
|
|
- **Two rules converging on one topic.** Merge them, keep the cross-references, and
|
|
delete the weaker. Fewer, sharper rules beat many overlapping ones.
|
|
|
|
## Deprecating a rule
|
|
|
|
A rule that no longer earns its tokens is removed deliberately, not deleted on a
|
|
whim and not left to rot.
|
|
|
|
1. **Mark it deprecated** in place, with the reason and any replacement.
|
|
2. **Provide the migration path** to the rule or behavior that supersedes it.
|
|
3. **Update dependents** that cross-reference it before removal.
|
|
4. **Remove it** once nothing points at it. A rule no longer used, no longer
|
|
accurate, or fully absorbed by another is dead weight; cut it.
|
|
|
|
## Keep the set lean
|
|
|
|
The rule set is read under load; every always-on rule is a recurring tax. Review
|
|
periodically for: rules no longer used, examples gone stale against current code,
|
|
clauses now covered better elsewhere, and pairs that should be merged. The goal is
|
|
the **smallest set of testable rules that prevents the recurring failures**, not
|
|
the largest set of plausible advice.
|
|
|
|
## DO
|
|
|
|
- Promote a pattern to a rule at ≥3 occurrences across files or sessions; promote a
|
|
repeated mistake at ≥2; promote repeated review feedback at ≥3.
|
|
- Promote on the first occurrence when stakes are high (security, data loss, wide
|
|
breaking change, new dependency, correctness invariant).
|
|
- Strengthen or merge an existing rule before adding a new one on the same topic.
|
|
- Record one-off corrections as notes and wait for the recurrence that earns a rule.
|
|
- Deprecate with a migration path; remove only after dependents are updated.
|
|
|
|
## DON'T
|
|
|
|
- Do not codify a one-off that the single correction already fixed, absent a
|
|
high-stakes reason.
|
|
- Do not turn a bare stylistic preference into a rule; that is configuration.
|
|
- Do not add a rule that overlaps an existing one; sharpen the existing one instead.
|
|
- Do not write a rule so specific it will fire exactly once more.
|
|
- Do not let deprecated or stale rules linger; they tax every session that loads
|
|
them.
|
|
|
|
## Acceptance check
|
|
|
|
A rule addition conforms when: (1) it cites the recurrence that justified it (the
|
|
files, sessions, or reviews where the pattern appeared) **or** names the high-stakes
|
|
reason that overrides the count; (2) a search confirms no existing rule already
|
|
covers the same ground, or the existing rule was strengthened instead; (3) the new
|
|
or updated rule itself meets `rules.md` (testable clauses, acceptance check, honest
|
|
example); and (4) any rule it supersedes is deprecated with a migration path, not
|
|
left to drift. A rule introduced on a single low-stakes occurrence, or one that
|
|
duplicates an existing rule, fails this check even if the rule's text is well
|
|
written.
|
|
|
|
## Companion rules
|
|
|
|
- `rules.md`: how to write the rule this file decides is warranted, testable
|
|
clauses, acceptance checks, honest examples, accurate binding strength.
|
|
- `no-shortcuts-first-principles.md`: the ethic behind leanness, the smallest
|
|
correct set, not the largest plausible one; disclosed limits over hidden bloat.
|
|
- `proof-discipline.md`: the standard a new rule's own acceptance check should meet.
|
|
|
|
## Why this exists
|
|
|
|
A rule set decays in two opposite directions, and both hurt. Under-codify, and the
|
|
same mistake recurs because the correction never became a check. Over-codify, and
|
|
the set fills with one-off advice that costs tokens every session while preventing
|
|
nothing, and the signal drowns. Explicit thresholds (recurrence counts for ordinary
|
|
patterns, a count of one for high stakes) keep the set growing only where growth
|
|
pays, and a deprecation path keeps it shrinking where it no longer does. Portable to
|
|
any rule set for any AI coding agent.
|