pattern-recognition
Pattern Recognition
Concept of the skill
Pattern recognition is the cognitive and methodological discipline of identifying recurring structures across instances — separating signal from noise, naming the structure once detected, and elevating it into durable, transmissible knowledge. Drawing from Gestalt perception (Wertheimer 1923), expert intuition research (Klein 1998 recognition-primed decision; Chase & Simon 1973 chess chunking — masters perceive board positions as small numbers of meaningful patterns), and the software-pattern tradition (Alexander 1977 A Pattern Language; Gamma et al. 1994 Design Patterns), it treats pattern as a class noun: a regularity worth naming because it explains many observations through one structure.
Replaces symptom-by-symptom fixing (which burns tokens and effort without building leverage) with systemic detection-and-prevention that addresses the recurring class. Solves the problem that an agent operating symptom-by-symptom can fix the same bug five times in five different files and never see that the underlying root cause produces another instance next week — while an agent recognizing the pattern can propose a systemic fix, write an automated detection rule, and prevent the entire class from recurring. In a high-velocity agentic environment, manual review scales poorly; pattern recognition lets agents "see" the codebase as a system of rules rather than a collection of files. The eval-as-pattern-test pipeline is the durable artifact — every recognized pattern should become a testable eval so future sessions verify they detect it reliably under new inputs; without the eval, a skill section about "null-vs-zero confusion" may be read and then misapplied on the next input (the agent learned the name but not the detection logic). Closes the loop with prevention: the goal is not detecting the pattern more reliably; it is restructuring the system so the pattern becomes impossible (type constraint, hook, architectural change, lint rule that fails CI).
Distinct from debugging, which fixes one specific bug — this skill identifies the recurring class behind many bugs and proposes a structural fix that prevents the whole class; the same "recurring bug" prompt routes to debugging for the immediate fix and to this skill for the systemic rule. Distinct from code-review, which judges quality of a specific change at PR scope — this skill systematically detects recurring structural issues across the entire codebase; the same "recurring violation in PRs" prompt routes to code-review for blocking the PR and to this skill for adding a lint rule. Distinct from diagnosis, which triages an unknown software failure into a problem class before debugging begins — diagnosis owns per-incident triage; this skill owns cross-incident class analysis. Distinct from refactor, which restructures code once a pattern is identified (refactor enacts the change; this skill decides what needs changing). Distinct from naming-conventions, which establishes the rules themselves (this skill detects violations of rules that already exist). Distinct from lint-overlay, which owns the rule machinery (this skill decides which patterns warrant a rule). Distinct from skill-infrastructure (skill library health tooling and structural-graph audits) and tool-call-strategy (per-action tool selection). Pattern recognition is to a codebase what epidemiology is to a city's public health — a doctor (debugging) treats one patient with one infection; the epidemiologist (this skill) notices that fourteen patients across three hospitals all have the same infection, traces it back to a contaminated water source (root cause), names the outbreak, prescribes a public-health intervention (lint rule, type constraint, architectural fix) that prevents the next thousand cases, and updates the surveillance protocol so the next outbreak is caught at three cases instead of fourteen. The wrong mental model is that every recurring observation is a pattern — that two similar bugs justify a framework, a lint rule, or a refactoring sweep. They do not. The three-instance threshold is load-bearing: one is a bug, two is a coincidence, three is a pattern. Premature codification creates false rules that block valid code and produces "pattern-inflation" (pareidolia — seeing patterns in noise) where the team responds to every coincidence with abstraction. Adjacent misconceptions: that similar symptoms imply a shared root cause (they do not — a cluster of "null reference" errors may have 3 different call sites with 3 different missing guards; verify each cluster member shares a root before proposing a unified fix); that fixing at the symptom level eventually fixes the pattern (it does not — the symptom loop is the most expensive form of pattern work; without the 5-Whys to the root level, every new instance generates a new fix; aim for level 4-5, not level 1-2); that abstractions are always proportional to pattern recurrence (they are not — building a framework or lint plugin for one pattern is over-abstraction; detection should be proportional to frequency: one pattern = grep rule; three patterns = lint plugin; complex wrapper harder to maintain than the duplication is its own anti-pattern); that every match is a violation (it is not — false-positive discipline matters: test fixtures are intentional, token files are exempt, inline // @intentional: comments document legitimate deviations; document exclusion rules in the grep pattern itself, not in memory); that detection rules are evergreen (they are not — patterns have lifecycle states: Active / Fixed / Stale / Migrated; a fixed pattern's detection rule should be archived; a migrated pattern requires dual detection of old AND new violations); and that naming a pattern is enough (it is not — pattern recognition completes the loop through Codify, Detect, Prevent, and ideally Eval; the eval step is non-optional because a skill section documents a pattern for humans, but an eval tests whether an agent applies the pattern reliably under new inputs).
Coverage
The methodology for identifying recurring structures across code, errors, board state, design systems, and domain data — then acting on them systematically rather than symptom-by-symptom. Names the six-step recognition loop (Observe → Cluster → Name → Codify → Detect → Prevent) with an optional Refine stage and the discipline at each stage. Catalogues code pattern classes (naming violations, duplication, anti-patterns, convention drift, missing guards, stale patterns) with detection methods and false-positive risks. Specifies the grep-based audit pattern as a six-step sequence (define → scan → count → sample → classify → triage) and the three-pass audit strategy (discovery → refinement → verification). Documents error-pattern clustering via normalize-then-hash extraction with ten error categories and severity-by-frequency triage rules. Names nine board-health patterns (stale in-progress, column overflow, WIP overflow, duplicate suspect, orphan in-progress, etc.) and the structural prevention each implies. Covers design pattern recognition (heading hierarchy contract violations, design token drift, triple-encoding requirement, component boundary violations) and domain-encoding patterns (null-vs-zero distinction, integer encoding for monetary amounts, magnitude-conversion at display boundary, source-rank trust hierarchy). Defines the eval-as-pattern-test pipeline and a 5-Whys ladder for root cause vs symptom analysis. Closes with pattern lifecycle states (Active / Fixed / Stale / Migrated), cross-session pattern persistence, a verification checklist, and six named drift traps (pareidolia, false clustering, stale patterns, over-abstraction, ignoring context, fixing at the wrong level).
Philosophy of the skill
Agents that operate symptom-by-symptom burn tokens without building leverage. An agent that recognizes patterns can propose systemic fixes, write automated detection rules, and prevent entire classes of bugs from recurring. This skill teaches the methodology — not just what to look for, but how to elevate a single finding into a durable detection and prevention mechanism.
The core discipline: require three instances before codifying a pattern. One is a bug. Two is a coincidence. Three is a pattern worth naming and automating. In a high-velocity agentic environment, manual review scales poorly — pattern recognition lets agents "see" the codebase as a system of rules rather than a collection of files. The premature codification of a pattern after one or two instances creates false rules that block valid code; the failure to codify after the third instance leaves the team to keep paying the same review cost on every future commit.