pattern-mining

name	pattern-mining
description	Test repeated implementation shapes against independent exemplars and a holdout before routing an earned abstraction. Triggers: "mine a recurring code pattern", "is this abstraction earned", "extract invariants from implementations".
practices	["design-patterns","legacy-code-seams","design-by-contract"]
hexagonal_role	supporting
consumes	["repo-context","task-question"]
produces	["pattern-mining.v1"]
context_rel	[{"kind":"customer-of","with":"research"},{"kind":"customer-of","with":"validate"},{"kind":"supplier-to","with":"operationalize"}]
skill_api_version	1
user-invocable	true
context	{"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"topic"}
metadata	{"capabilities":["pattern_mining"],"effects":["write_pattern_evidence"],"canonical_status":"canonical","disposition":"keep_specialist","tier":"execution","dependencies":[]}
output_contract	pattern-mining.v1 JSON validated by skills/pattern-mining/scripts/validate-output.sh

Pattern Mining

Decide whether repeated code demonstrates a reusable rule or only a plausible hypothesis. Similar names and syntax are not enough; the abstraction must survive examples it was not designed around.

Constraints

• To prevent lineage copies from faking recurrence, use independently implemented exemplars with repository anchors.
• Because the candidate must generalize, form it without seeing the holdout and back-apply every holdout-driven refinement.
• To keep weak evidence from becoming architecture, route hypotheses to no-action; only a fully proven promotion may reach operationalize.

Workflow

1. State the candidate pattern and collect independently implemented exemplars with repository anchors. Use research when coverage is unclear.
2. From the exemplars, separate required invariants, legitimate variation points, and incidental similarity.
3. Require at least three distinct exemplars before promotion is possible. Form the candidate abstraction without using the holdout.
4. Test it against every exemplar, then a separate holdout. Back-apply the refined abstraction to the original exemplars so the holdout fix cannot silently break them.
5. Emit outcome: promote only when the exemplar floor, holdout, and back-application all pass. Route that evidence to operationalize, which decides whether the eventual shape is a skill, gate, library, template, or no action.
6. Otherwise emit outcome: hypothesis with route: no-action. Keep the evidence bounded and name what additional observation would retest it.

Diff/align across exemplars

Invariants are extracted mechanically, not remembered. Lay the exemplars side by side, align them structurally (same role, same position in the flow — not same variable names), and diff: what survives every alignment is a candidate invariant; what varies by site is a variation point; what varies with no functional consequence is incidental. Work pairwise before generalizing — an "invariant" derived by skimming all exemplars at once is usually the first exemplar's shape with the others squinted into agreement. Stop condition: every line of the candidate abstraction is traceable to a surviving alignment across all exemplars, or it is deleted. The named failure mode is eyeball convergence — declaring similarity from memory of the files rather than from an explicit alignment, which smuggles one lineage's incidentals into the rule.

Explicit search recipes

Exemplar discovery is part of the evidence and must be replayable. Record the exact queries used — rg patterns, glob scopes, structural searches — in the output packet, alongside which hits were kept and why the rest were excluded. A recipe that returns hits you did not examine is unfinished coverage: either examine them or narrow the recipe and record the narrowed form. The named failure mode is convenience sampling — mining only the files already in context, which biases the exemplar set toward one author or one era of the codebase and fakes independence at step 1. If no recipe can be written that finds the exemplars, the recurrence claim is unverifiable and the outcome stays .