docs-hygiene extract-ssot: reconsider the Rule of Three gate as a threshold of two with a judgment-based legitimate-divergence check

[kyle-sexton]

Summary

extract-ssot's headline refusal gate is the Rule of Three (Don
Roberts / Fowler) — it refuses extraction below 3 instances, on the basis
that premature abstraction is the dominant failure mode. This issue
proposes reconsidering that default as a threshold of two, paired with
a judgment-based legitimate-divergence check that replaces the blunt
count as the real decision.

Current behavior (grounded)

• SKILL.md frontmatter: "refuses extraction below the Rule of Three."
• Body: "If the same unit of prose appears 3+ times … collapse to one
  definition … Below 3 instances, inline is the disciplined call —
  premature abstraction is the dominant failure mode."
• The gate is empirically motivated: the skill cites ~19% extraction-failure
  rate on curated skills and ~50% on practitioner-authored skills.
• The skill already contemplates the change: its deferred-trigger table
  lists "Practitioner-authored skill failure rate drops below 20% … consider
  relaxing Rule of Three to Two for low-risk vocabulary."

Motivation

The owner's dedupe doctrine sets the duplication threshold at two, not
three: a passage, literal, or concept living in two or more places (verbatim
or reworded) is duplication to resolve by pointing, not something to tolerate
until a third copy appears. This doctrine is now embodied in the new
/re-anchor:point-dont-copy corrector (#249), which audits for duplication
at a threshold of two. extract-ssot's Rule-of-Three gate is the one place
in the marketplace that still encodes three as the default, creating an
inconsistency a consumer will hit when they route a two-copy cluster to
extract-ssot after point-dont-copy flagged it.

Proposal

Change the default gate from "refuse below 3" to "consolidate at 2, unless
a legitimate-divergence check passes":

1. Threshold of two. Two instances that change together and have a
   namable identity are candidates for extraction, not an automatic refusal.
2. Judgment-based legitimate-divergence check replaces the count. The
   real question is not "how many copies" but "should these stay separate on
   their merits" — e.g. the two instances are diverging deliberately, one is
   a contract token that must stay inline, or extraction would drag unrelated
   context. The existing 6-test gate (namable, stable, self-contained,
   bounded, one-level-deep) already carries most of this; this change makes
   the count subordinate to the judgment rather than a hard floor.
3. Preserve the empirical caution as guidance, not a blanket floor. The
   ~19–50% failure data is real; keep it as a WARN / ROI caution and the
   reversibility guardrails, but stop letting a bare count veto a genuine
   two-copy consolidation.

Open questions

• Does the empirical failure data hold at threshold two, or should the
  relaxation be scoped (the deferred trigger scopes it to "low-risk
  vocabulary")? The divergence check may be where that scoping lives.
• How does this interact with the deferred trigger already in the skill —
  does this issue supersede it, or refine its condition?

Filed as part of the round-2 personal-skill graduation; point-dont-copy
(#249) is the reactive corrective that motivated surfacing the threshold
inconsistency.

[kyle-sexton]

Decision brief: Rule of Three gate — keep, lower to two, or make two a review-flag?

Brief-writer lane. This is decision support only — no label/close/merge action taken. Human operator decides.

Problem (2 sentences)

extract-ssot hard-refuses prose extraction below three duplicate instances (Rule of Three), while the owner's own dedupe doctrine — now encoded in /re-anchor:point-dont-copy (#249) — treats duplication as resolvable at two. The question is whether to lower the gate to two with a judgment-based legitimate-divergence check, and if so, whether "two" should auto-extract or only surface as a reviewable candidate.

What's verified today (in the actual skill)

Current gate, cited against plugins/docs-hygiene/skills/extract-ssot/ on the default branch:

• The count is a hard floor. SKILL.md:3 frontmatter — "refuses extraction below the Rule of Three"; SKILL.md:84 — "Headline gate: Rule of Three (Don Roberts / Fowler) — refuse extraction at <3 instances"; SKILL.md:15 — "Below 3 instances, inline is the disciplined call — premature abstraction is the dominant failure mode." Pre-extraction checkpoint requires "3+ instances confirmed via grep" (SKILL.md:144).
• A legitimate-divergence check already substantially exists. This is the load-bearing finding. context/decision-framework.md already runs judgment checks that decide "should these stay separate on their merits": Test D — "Instances differ in non-trivial ways and would force conditionals/flags inside the SSOT" → keep inline (decision-framework.md:27); the off-by-one different-concern heuristic — "Step counts / variant shapes diverge non-trivially → REFUSE-off-by-one-different-concern; intentional Path 1/Path 2 bifurcations are preserved" (decision-framework.md:44); and the LOW-ROI threshold (decision-framework.md:45). So the proposal's "add a divergence check" is mostly a reclassification of the two-instance outcome, not new machinery.
• At two today, the behavior is REFUSE-with-tracking-note, not a silent wall. The worked example (decision-framework.md:149-156) refuses two instances citing Rule of Three and offers to record a tracking note to revisit when the third lands. The friction with feat(re-anchor): add discipline-corrector plugin #249 is real (in an autonomous flow a two-copy cluster routed here auto-refuses), but the status quo is softer than a blind veto.
• The skill already set itself a data-gated path to two. Deferred trigger (SKILL.md:181): "Practitioner-authored skill failure rate drops below 20% (SkillsBench refresh) → consider relaxing Rule of Three to Two for low-risk vocabulary." The proposal would relax before that data threshold is met, and would broaden beyond "low-risk vocabulary."
• Empirical caution is prose-specific and measured under the three-gate. SKILL.md:23 — "~19% failure rate even on curated skills (SkillsBench, n=84), ~50% on practitioner-authored skills." The failure rate at two is unknown — these numbers were observed with the three-gate in force.

External grounding (Rule of Three vs a threshold-of-two-with-judgment)

• "Three" is a rule of thumb, not an empirically derived constant. Popularized by Fowler's Refactoring (1999), attributed to Don Roberts ("three strikes, then you refactor"); it descends from the "Three Examples" pattern in Roberts & Johnson, Evolving Frameworks (1996). Its stated justification is the wrong-abstraction asymmetry, not the number itself: more examples let you see the real pattern, and a premature/wrong abstraction is expensive to unwind (Wikipedia: Rule of three).
• The exact number is genuinely contested in the literature. Sandi Metz's "The Wrong Abstraction" (2016) — "duplication is far cheaper than the wrong abstraction" — argues for waiting (favoring three or more). The counter-camp (e.g. Jason Swett) argues duplication is almost always worth removing (favoring two). Neither side sanctifies a number; both are really arguing the over-extraction-risk vs. missed-duplication-risk tradeoff.
• Implication for this skill: the code literature does not make "three" load-bearing — it makes the judgment about whether the abstraction is right load-bearing, with count as a proxy. That directly supports subordinating the count to the divergence check. The one caveat: the wrong-abstraction asymmetry the literature warns about is a code asymmetry (params/conditionals proliferating); for well-bounded prose vocabulary the asymmetry may be weaker — which is exactly what the skill's "low-risk vocabulary" scoping targets.

Options

(C) — RECOMMENDED — Two becomes a WARN / surfaced review-candidate, not a hard REFUSE; three stays the auto-proceed floor.
Delta from today: two instances move from REFUSE-with-tracking-note to a WARN/flagged-candidate that runs the divergence checks that already exist (decision-framework.md:27,44,45); pass → present as a reviewable extraction candidate, not a silent auto-extract. Scope the relaxation to the "low-risk vocabulary" the skill already named (SKILL.md:181).

• Why first: Resolves the exact feat(re-anchor): add discipline-corrector plugin #249 seam (a two-copy cluster is no longer auto-rejected) while preserving the empirical caution (SKILL.md:23) as a WARN rather than discarding the floor. It maps onto the skill's existing PROCEED | REFUSE | WARN verify output (SKILL.md:72) and the divergence checks that already run — minimal new machinery. It honors the skill's own data-gated deferred trigger instead of superseding it wholesale.
• Tradeoffs: Adds/uses a state rather than "just consolidate at two"; doesn't fully satisfy the proposal's "consolidate at 2" wording.
• Reversibility: High. A WARN threshold is a tuning knob — trivially tightened back to three or promoted to auto-proceed once failure-rate-at-two data exists.

(B) — Lower to two + legitimate-divergence check auto-extracts (the proposal as written).
Two + divergence-check-pass → auto-extract; keep the 19–50% data as ROI/WARN guidance.

• Tradeoffs: Fully resolves the inconsistency and matches the two-threshold doctrine. But it lets a softer judgment gate license auto-execution in autonomous sessions, where an agent can rationalize past a "should these stay separate?" check more easily than past a count; and it acts before the skill's own data trigger (SKILL.md:181) is satisfied. Over-extraction risk is real and, at two, unmeasured.
• Reversibility: Lower — already-executed extractions must be Metz-unwound; walking back after a failure-rate spike is costlier than retightening a WARN.

(A) — Keep Rule of Three as-is.

• Tradeoffs: Lowest over-extraction risk; matches the code-literature default and the intact empirical caution. But it leaves the one place in the marketplace encoding three as default inconsistent with the owner's own two-threshold doctrine (feat(re-anchor): add discipline-corrector plugin #249), preserving the seam friction the issue was filed to remove.
• Reversibility: N/A (no change).

Open question to carry (not resolved here)

Does the 19%/50% failure data hold at threshold two? It was measured under the three-gate; the rate at two is unknown. This is the single fact that should gate any move from C's WARN state to B's auto-extract — and it is the same condition the skill's deferred trigger (SKILL.md:181) already names.

Sources: Wikipedia — Rule of three (computer programming); Sandi Metz — The Wrong Abstraction (2016); Jason Swett — the counter-argument.

[kyle-sexton]

This was generated by AI during triage (operator-ratified decision, 2026-07-24).

Decision: adopt a test-ordered matrix; count subordinated to judgment

Operator ratified after a deep-research pass (24 sources, 25 claims adversarially verified 3-0/2-1, 1 refuted). This supersedes the A/B/C framing of the decision brief above: the resolution is neither "keep three" nor "flat two" — the copy count stops being a gate and becomes evidence inside the judgment tests.

What changes in extract-ssot

Replace the hard "refuse below 3 instances" floor (frontmatter, headline gate, pre-extraction checkpoint) with this ordered sequence — first decisive test wins:

1. T1 — Same knowledge or coincidental? Identical text encoding different knowledge → never consolidate (Hunt/Thomas coincidence rule; consolidation actively harms).
2. T2 — Crosses an encapsulation boundary? Bounded-context/service/availability seams → duplication correct by design (DDD divergent models, event-carried state transfer); consolidate only via an explicit owned decision.
3. T3 — Change-together acid test. One fact forcing edits in multiple places/formats (including code+docs pairs) → true knowledge duplication; consolidate now, even at two copies.
4. T4 — Abstraction namable and stable? Not namable → keep the wait-for-third brake (this is the Rule of Three's real job: wrong-abstraction avoidance). Namable → two suffices.
5. T5 — Reversibility. Cheap inline-back → early consolidation low-risk; load-bearing/hard-to-unwind → demand the third occurrence as evidence.
6. T6 — Churn/friction. High co-change frequency → consolidate earlier; static content tolerates copies longer.

The skill's existing divergence machinery (decision-framework Test D, off-by-one-different-concern, LOW-ROI) already implements most of T1/T4 — this is a reclassification of the two-instance outcome plus an explicit ordering, not new machinery. The ~19%/50% SkillsBench failure data stays as a WARN/ROI caution, not a count floor. The existing deferred trigger ("relax to two when failure rate <20%") is superseded by this decision.

Constraints for the implementer

• Do not present the Rule of Three as a cost calculus — "three copies = maintenance cost definitively outweighs refactoring cost" was refuted 0-3. It is a permissive heuristic brake, never a prohibition on extraction at two.
• Cite Metz / Dodds / Swett / Pike as links, not load-bearing attributions — those camps had no surviving primary-verified claims in the research run.
• Prose overlay applies: knowledge-bearing docs content consolidates from first reuse (DITA single-sourcing posture); audience-/context-sensitive prose legitimately duplicates (Write the Docs); reuse-eligibility alone never justifies consolidation.

Cross-repo doctrine

The org-wide posture is codified separately in melodic-software/standards#263 (engineering-philosophy). Once that lands, this skill should cite it as the single source of truth rather than restating the matrix; alignment of /re-anchor:point-dont-copy with the same posture rides the same standards item.

Key verified sources

• https://media.pragprog.com/titles/tpp20/dry.pdf (DRY = knowledge, acid test, coincidence rule — verbatim)
• https://www.artima.com/articles/orthogonality-and-the-dry-principle (Thomas: DRY beyond code)
• https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming) (rule is permissive about two; no empirical grounding for exactly-three)
• https://blog.jbrains.ca/permalink/clarifying-the-rule-of-three-in-refactoring/ (Rule of Three as pedagogical guardrail)
• https://martinfowler.com/bliki/BoundedContext.html + https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-domain-driven-design (divergent models intended)
• https://martinfowler.com/articles/201701-event-driven.html (event-carried state transfer: duplication as priced tradeoff)
• https://www.oreilly.com/library/view/dita-best-practices/9780132374323/ch10.html + https://www.writethedocs.org/videos/portland/2022/don-t-shoot-yourself-in-the-foot-with-content-reuse-anna-gasparyan/ (prose overlay)