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.

1. The Pattern Recognition Loop

Observe → Cluster → Name → Codify → Detect → Prevent
   ↓         ↓        ↓       ↓         ↓         ↓
See it    Group     Give it  Write    Automate   Make it
3x+       similar   a name   a rule   checking   impossible

An optional Refine stage closes the loop: monitor the effectiveness of the fix and update the codified rule if false positives emerge or the pattern mutates.

Discipline at each stage

• Observe: Do not claim a pattern after one instance. Two = coincidence. Three = pattern. Premature codification creates false rules that block valid code.
• Cluster: Group similar instances and verify they share a root cause. Similar symptoms may have different roots — a null pointer and a type error both cause crashes, but fixing null checking does not fix the type error. Group by symptom first, then verify each member shares a root.
• Name: Give the pattern a name short enough to grep for (3–5 words). A pattern named "bad cost handling" is unsearchable. "null-vs-zero cost confusion" is greppable, discussable, and findable in evals. If you cannot name it concisely, it is too vague to be actionable.
• Codify: Document the pattern in a skill section, a rules file, or a lint rule so it can be searched, discussed, and taught to other agents. Include the detection method (grep pattern, file check, or manual review trigger).
• Detect: Automate detection via eval, lint rule, board-health check, or file watcher. Detection should be on-by-default and produce a signal (warn, fail, or task creation) when the pattern is found — not dependent on human memory.
• Prevent: Restructure the system so the pattern becomes impossible. Examples: a type-system constraint that prevents the null-pointer pattern, a hook that enforces the session-closeout protocol before session end, a lint rule that blocks the pattern from merging, or an architectural change that eliminates the root cause entirely. Structural prevention is the goal when the cost is proportionate; not all patterns reach this stage.

2. Code Pattern Detection

Pattern classes and detection methods

The grep-based audit pattern

For any code pattern, the detection method follows this sequence:

1. Define the pattern as a regex specific enough to minimize false positives, with scope (which files, which languages).
2. Run the scan with appropriate include / exclude filters.
3. Count matches first — output_mode: "count" or | wc -l gives scale before committing to review. >20 matches = significant systemic issue.
4. Sample matches — output_mode: "content" with head_limit: 10 confirms the pattern is real.
5. Classify — true positive (genuine violation) vs false positive (intentional or contextual).
6. Triage — fix trivial matches in one commit, create a tracker issue for architectural fixes, or add a lint rule for prevention.
7. Verify prevention — if you add a lint rule, confirm it catches the pattern in a test commit before shipping.

The 3-pass audit strategy

1. Discovery pass: broad, case-insensitive grep to find potential candidates.
2. Refinement pass: regex lookaheads/lookbehinds or -v exclusions to remove known intentional patterns (vendor code, token files, fixtures).
3. Verification pass: read 3–5 random samples manually to confirm true-positive status before acting on the whole set.

Example: detecting hardcoded colors

# Find hardcoded hex in component styles (excluding token sources)
grep -rE '#[0-9a-fA-F]{3,8}' src/ \
  --include='*.scss' --include='*.module.scss' \
  | grep -v '_design-tokens.scss' \
  | grep -v '_foundation.scss' \
  | head -20

# Each match: file:line → replace with var(--color-*) token from your token-source file

Example: detecting stale ticket-prefix references

# After renaming a project's ticket prefix from OLD- to NEW-, any OLD- reference is stale
grep -rE "OLD-[0-9]+" . --include='*.md' --include='*.ts' --include='*.js'
# → Replace OLD-XXXX with NEW-XXXX

Example: detecting unguarded mutations

# DELETE without WHERE — data-safety violation
grep -rE 'DELETE FROM' . --include='*.ts' --include='*.sql' | grep -v 'WHERE'

# UPDATE without tenant-scope filter — multi-tenant isolation violation (requires manual review)
grep -rE 'UPDATE.*SET' src/ --include='*.ts' | head -20
# For each match: verify the tenant-id filter is in the WHERE clause

False-positive discipline

Not every grep match is a violation. Before filing or fixing:

• Check if the match is inside a test fixture (intentional by definition).
• Check if the match is inside a comment documenting the old pattern (informational, not active).
• Check if the file is explicitly excluded from the convention (e.g., a token file is allowed to contain hex literals).
• Check if there is an inline exemption comment (// @intentional: <reason>).

Document false-positive exclusion rules in the grep pattern itself, not just in memory. A rule that only exists in your head will be rediscovered and re-debated by the next agent.

3. Error Pattern Clustering

A deterministic error-extraction phase (no model involved, no hallucination risk) clusters session-log errors into actionable categories.

Error categories and responses

Clustering method

1. Extract error messages from the session log (deterministic — no model involved).
2. Normalize each error: strip timestamps, file paths, line numbers, variable names, session IDs.
3. Hash the normalized message to group identical errors into buckets.
4. Count occurrences per hash → frequency is the primary severity signal (5+ = systemic issue).
5. Deduplicate against existing tracker issues via Levenshtein similarity → prevent duplicate tickets for the same error class.
6. Classify each bucket: real pattern vs one-off instance; edge cases require manual review.

Key insight: normalizing before hashing is what makes clustering work. Two errors that look different because one says line 47 and the other says line 52 are the same error. Strip the specifics first.

When clusters point to root causes

A cluster of 8 "Cannot read property of undefined" errors normalized to the same code path means there is one missing null guard, not 8 bugs. Fix the guard once; the cluster disappears. If the errors normalize to 3 different code paths, there are 3 root causes — do not collapse them into one ticket.

When to file a tracker issue from an error pattern

• Frequency ≥5 in one session OR ≥3 across recent sessions → file a bug task.
• Blocking task completion → file immediately regardless of frequency.
• Prevents the agent from proceeding → escalate to an infrastructure task.
• Root cause is addressable (missing feature, not "agent made a mistake") → prioritize for implementation.
• If the root cause is agent logic, defer to post-mortem; do not task the infrastructure.

4. Board-Health Patterns

A board-health checker can detect nine board-level patterns. Each implies a process fix, not just an alert.

Using patterns for prevention

Each pattern implies a structural fix:

Pattern interaction: WIP overflow + stale in-progress

These two patterns frequently co-occur: WIP overflow happens because agents claim tasks and then stall, creating stale in-progress tasks. The root cause is not "too many tasks claimed" but "tasks are claimed without a completion guarantee." The fix is a closeout protocol that forces resolution (Done or Blocked) before a new task can be claimed.

Triage action, not just reporting: when a pattern is detected, move stale tasks to Ready, flag duplicates for merge, and ping the owner of dependency deadlocks.

5. Design Pattern Recognition

Heading hierarchy contract violations

A heading hierarchy contract defines (typically) six semantic levels mapped to typography tokens with a strict component → level map. Pattern detection:

# Components defining their own font-size (violation of the contract)
grep -r "font-size:" src/ --include='*.module.scss' \
  | grep -v '_foundation.scss' | head -20

# Components with hardcoded font-weight (should use heading token)
grep -r "font-weight:" src/components --include='*.scss' | head -20

Rule: no component may define font-size, font-weight, or font-family for headings. Use the foundation heading tokens or semantic HTML (<h1>–<h6>) with foundation styles. If a title needs different styling, the heading hierarchy is wrong — fix the hierarchy in the token source, not the component.

Triple-encoding verification

Status meaning in any UI should be "triple encoded": color + icon + text.

• Violation: a badge that uses green color but no checkmark icon, or an icon with no accompanying text label.
• Detection: check component props for icon and variant alignment; run an accessibility audit for color-only signals.
• Why: color-only encoding fails for colorblind users and monochrome rendering.

Design token drift patterns

Component pattern violations — enforcement

Document the contract in a design guide and enforce via:

• ESLint / Stylelint rules that catch hardcoded values.
• A design-review checklist for PRs.
• Evals that test design compliance.
• A heading-audit script for semantic-hierarchy checks.

Why design-pattern detection is high-leverage

A single hardcoded color in one component is a one-line fix. But the same hardcoded color appearing in 15 components means a developer practice is broken — adding a new component will likely introduce color 16. The fix at the root-cause level is: (a) a lint rule that fails CI on hardcoded colors, and (b) a design-review gate before merge. Fixing 15 instances without the lint rule means instance 16 will appear next sprint.

6. Domain-Encoding Patterns

Every domain has encoding conventions that, when misread, produce silent incorrect calculations — the most dangerous class of bug because the output looks valid. Monetary amounts are the classic example, but the same principles apply to any domain primitive (timestamps, percentages, dimensions, weights, currency codes).

Domain-encoding pattern detection

# Premature minor → major conversion (may lose precision mid-chain)
grep -r "/ 100" src/ --include='*.ts' \
  | grep -E 'cents|price|cost|total'

# Confusion between zero and null in domain fields
grep -r "amountCents === 0" src/ --include='*.ts' | head -10
# → verify the logic correctly distinguishes "unknown" from "zero"

# toFixed on minor units (wrong magnitude)
grep -r "toFixed" src/ --include='*.ts' | grep -v '/ 100'

# Missing minor → major formatting at the UI boundary
grep -rE "\{.*_cents\}" src/components/ | grep -v 'formatMoney'

# Unguarded division that could NaN
grep -r "safe-percent\|safeRatio\|safeDiv" src/ --include='*.ts' | wc -l
# → if the count is low, there may be unsafe divisions elsewhere

The null-vs-zero trap

This is a high-frequency domain-encoding pattern violation in any codebase that handles partial data. The invariant: null means "we don't know," 0 means "we know and it's zero." Code that treats them identically will either:

• Report a successful outcome when it is actually unknown (null cost → fake zero cost → fake 100% margin).
• Hide genuine zero-value cases as unknowns.

Always write explicit checks:

if (amountCents === null) return null; // unknown, not zero

The lesson generalizes beyond money: a lastSeenAt of null ≠ "seen at epoch zero"; an unknown shipping weight ≠ a zero-weight package; a missing assignedTo ≠ "assigned to no one on purpose." Build the null-vs-zero distinction into the type system at the boundary, and propagate it through the calculation chain.

7. The Eval-as-Pattern-Test Approach

Every recognized pattern should become a testable eval. This is how patterns survive beyond the session that discovered them — agents in future sessions can verify they detect the pattern reliably under new inputs.

{
  "id": 1,
  "name": "heading-hierarchy-violation-detection",
  "prompt": "Review this SCSS for design token compliance:\n.chart-title { font-size: 16px; color: #333; font-weight: 600; }",
  "expected_output": "Identifies #333 and font-size: 16px as token violations",
  "expectations": [
    "Flags #333 as hardcoded color — should use a color token",
    "Flags font-size: 16px as raw value — should use a heading token or semantic <h3>",
    "Does NOT flag font-weight: 600 if it matches the heading-h3 spec",
    "Does NOT flag colors inside the token source files"
  ],
  "model": "any frontier model"
}

Pattern → eval pipeline

1. Detect the pattern manually in a session (this document, codebase scan, or error clustering).
2. Write a skill section documenting the pattern, detection method, and fix.
3. Capture the offending code snippet to evals/fixtures/.
4. Create an eval in evals/patterns.json that tests detection with known inputs and expected outputs.
5. Run the eval to verify agents can detect it reliably in zero-shot review.
6. Automate detection in CI (lint rule, grep gate, or board-health check).
7. Verify the automated check catches the pattern in a test commit before shipping.
8. Document the pattern in the relevant canonical doc (design guide, security policy, data-handling spec).

Why the eval step is non-optional

A skill section documents a pattern for human readers. An eval tests whether an agent can apply the pattern 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. The eval closes that gap.

Evals

This skill ships evals/evals.json with scenarios for recurrence thresholds, convention drift, error clustering, board-health patterns, root-cause depth, pattern lifecycle states, and negative routing boundaries. The eval artifact is intentionally kept as ordinary scenario JSON rather than a repo-specific fixture suite because the skill is portable and teaches a cross-codebase method.

8. Root Cause vs Symptom Recognition

Agents that fix symptoms create the illusion of progress while the root cause generates new instances. Pattern recognition locates the level at which a fix propagates to all instances.

The 5-Whys for agents

Work down to the level where a fix prevents all future instances, not just the current one.

Example: repeated null-check bug

1. Why does this calculation crash? → amountCents is null, no guard exists.
2. Why is the guard missing? → The function assumes the amount is always recorded.
3. Why does it assume that? → No type constraint enforces nullable amounts.
4. Why no type constraint? → The function accepts number instead of number | null.
5. Why the wrong type? → The type was copied from an older schema before the field became nullable.

Fix at level 5: update the type signature to amountCents: number | null, add a comment explaining the null semantics, run type-check across all callers. This prevents the bug for all future callers, not just the one that crashed today.

Fixing at level 1 (add || 0) silently converts "unknown" to "zero assumed" — the wrong fix that creates a new category of silent error. Always aim for level 4–5 when possible. Levels 1–2 are debugging; levels 4–5 are process improvement.

9. Pattern Lifecycle Management

Patterns are not permanent truths. They require maintenance.

Pattern states

Pruning stale detection rules

A detection rule for a pattern that no longer exists creates false positives and alert fatigue. After a root-cause fix ships:

1. Run the grep / lint rule: if zero matches, the pattern is gone.
2. Archive the detection rule with a note: "Fixed in commit XXXXXXXX — null-vs-zero domain-value type was corrected."
3. Keep the skill section (documents WHY the fix was needed) but mark detection as [archived].

Migrated patterns require dual detection

When a convention changes (e.g., the ticket prefix is renamed from OLD- to NEW-), the detection rule must flag:

• Old pattern: still-existing OLD- references (violations to fix).
• New pattern: any new OLD- references introduced after migration (regressions to prevent).

A single grep covers both: OLD-[0-9]+ catches all instances regardless of when they were written.

Detection decay

A detection rule added today may not catch future variants of the same pattern. Periodically verify that your detection rules still catch the pattern class, not just the specific instances you fixed. Rules age; patterns mutate.

10. Cross-Session Pattern Persistence

Patterns span multiple sessions. Track them so discovery is not repeated:

• Memory file: save significant patterns to a file like memory/pattern-<name>.md with detection method and prevention status.
• Tracker tasks: file bugs for high-frequency patterns; link tasks to the pattern for traceability.
• Lint / eval: add automated checks so future agents detect the pattern without rediscovery.
• Canonical docs: update the design guide, security policy, or data-handling spec to document the pattern and its rule.

If you detect a pattern that was supposedly fixed, investigate:

• Is the fix incomplete? (Some instances still exist.)
• Did a new instance slip through the detection rule? (Rule is incomplete.)
• Was the prevention mechanism removed? (Regression in process or codebase.)

Verification

Before codifying a pattern, confirm:

• Observed at least 3 times? One is a bug, two is a coincidence. Three is a pattern.
• Same root cause across instances? Similar symptoms ≠ pattern if roots differ.
• Can name it in 3–5 words? "Hardcoded color instead of token" ✓ vs "design issue" ✗.
• Can write a detection rule? A grep pattern, lint rule, or board-health check exists or can be added.
• Root cause identified, not just symptom? 5-Whys applied; the fix prevents recurrence.
• Pattern documented? Skill section, rules file, design rule, or security/data-handling policy doc.
• False-positive exclusions documented? Test files, token files, legacy-exempt areas — inline in the grep pattern.
• Detection automated? Lint runs on CI, eval runs on pilot, or check is in the board-health pipeline.
• Eval created for high-frequency patterns? Agents verify detection under new inputs.
• Prevention possible? Architecture change, type-system guard, or process hook can make the pattern impossible.
• Checked the inverse? Places where the pattern should be applied but isn't (e.g., guards missing at new callsites).

Drift Traps

1. Pattern inflation (pareidolia) — Not everything is a pattern. Require 3+ instances before codifying. A single bug is a bug; calling it a pattern adds false urgency and misleads future agents. Seeing patterns where only random noise exists wastes effort.

2. False clustering — Similar symptoms often have different root causes. 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.

3. Stale patterns — Patterns that were fixed but whose detection rules remain. A grep that always returns zero matches is noise and creates alert fatigue. Prune periodically; see §9.

4. Over-abstraction — Creating a framework or lint plugin to detect one pattern. Detection should be proportional to frequency. One pattern = grep rule. Three patterns = lint plugin. A complex wrapper that is harder to maintain than the duplication itself is its own anti-pattern.

5. Ignoring context — A pattern in test code may be intentional by design (e.g., testing null handling, hardcoded fixture values). A pattern in a token source file is by definition the source of truth. A pattern in a config file may be valid (comments that look like code). Context determines whether a match is a violation.

6. Fixing at the wrong level (symptom loop) — See §8. Fixing symptoms without the 5-Whys produces fix churn. Measure whether the cluster shrinks after the fix; if not, you fixed a symptom. Repeatedly addressing the 1st Why without ever reaching the 5th Why is the most expensive form of pattern work.

When NOT to declare a pattern

• Single instance — fix the bug; do not create a framework for it.
• Legitimate deviation — some code intentionally violates a rule. Document the reason inline (e.g., // @intentional: dynamic SQL interpolation required because...).
• Tool limitation — if you cannot write a detection rule because the tool is limited, either fix the tool or document the limitation.
• Unclear root cause — if you see similar symptoms but cannot determine a shared root cause, classify as "investigate further" not "pattern found".

Do NOT Use When

Key Sources

• Alexander, C., Ishikawa, S., & Silverstein, M. (1977). *A Pattern Language: Towns,

…(truncated)