Use this skill to identify repeated implementation patterns in a codebase, extract reusable conventions, and turn them into guidance without overfitting. The goal is not to write a style guide from taste. The goal is to describe implementation moves that the codebase already repeats for good reasons.
When To Use
Use this when a task asks for codebase conventions, local patterns, reusable implementation guidance, onboarding notes for how code is built here, or a pattern inventory before implementing similar work.
Do not use this to justify a preferred design that is not already present in the codebase. Do not promote one example into a convention unless you can explain why it generalizes.
Mining Workflow
-
Define the scope. Name the subsystem, language, framework, and artifact types being mined. Keep the scope narrow enough that examples are comparable.
-
Find candidate repetitions. Use repository search and code navigation to collect examples of recurring implementation moves: module boundaries, constructors, adapters, validation, error handling, persistence, tests, configuration, CLI flags, API shapes, and naming schemes.
-
Build evidence sets. For each candidate pattern, collect at least three independent examples when possible. If there are only two examples, mark the result as a weak signal unless those examples are central, recent, and deliberately parallel.
-
Separate convention from coincidence. Ask what stays stable across the examples and what varies. Preserve only the stable implementation move as the convention. Treat names, ordering, helper choice, and file layout as incidental unless the evidence shows they carry meaning.
-
Check counterexamples. Search for code that solves the same problem differently. A counterexample does not kill the pattern by itself; it defines the boundary where the convention applies, reveals migration drift, or exposes a competing local convention.
-
Extract guidance. Turn each accepted pattern into a short rule of use: when to apply it, how to implement it, which example is the clearest exemplar, what to avoid, and what would be overfitting.
-
Verify against likely future work. Test the guidance against a plausible new implementation. If following the guidance would force irrelevant details from the examples, narrow the rule.
Pattern Quality Bar
A mined pattern is strong when it has repeated independent examples, a clear reason to exist, consistent behavior, and useful boundaries. It should help a future implementer make fewer local-design decisions without copying irrelevant details.
A mined pattern is weak when it is based on one file, one author's habit, old code that newer code no longer follows, generated output, tests that intentionally use odd shapes, or examples that share only superficial structure.
Overfitting Guardrails
- Prefer behavior and intent over syntax trivia.
- Name confidence: strong, medium, or weak.
- Include counterexamples and explain whether they are exceptions, drift, or a separate pattern.
- Avoid universal words like always and never unless the repository provides broad evidence.
- Preserve useful variation. If examples differ safely, the guidance should say what can vary.
- Do not require new abstractions just because examples share a shape.
Report Format
Return a compact report with these sections:
# Implementation Pattern Mining
Scope: <subsystem, language, artifact types>
## Pattern Inventory
### <Pattern Name>
Confidence: strong|medium|weak
Evidence:
- <file or symbol>: <what it shows>
- <file or symbol>: <what it shows>
Convention:
<one or two sentences describing the reusable implementation move>
Guidance:
<how to apply it to new work>
Boundaries:
<where it applies, where it does not, and known counterexamples>
Overfitting Risk:
<details from the examples that should not be copied blindly>
## Candidate Patterns Not Promoted
- <candidate>: <why evidence was insufficient or too context-specific>
Handoff Rules
When handing the result to an implementer, keep the guidance executable: reference concrete examples, state the confidence level, and call out what is optional. If the output will become durable documentation, remove weak patterns or label them explicitly as observations rather than conventions.