Distill Patterns: $ARGUMENTS

$ARGUMENTS optionally scopes the mining to a subtree or a dimension ("error handling in the API layer"); empty = the whole codebase, all dimensions below.

Principle

Every codebase teaches by example — and its next contributor is an agent that learns the house style from whatever code it happens to read. If three error-handling styles coexist, generated code picks one at random; if the dominant example is bad, every generated line copies the rot forward. Consistency isn't aesthetics: it's the difference between a codebase that compounds and one that decays with each addition.

This skill closes the loop: mine the recurring patterns actually present, verdict each one deliberately instead of letting frequency decide, and install the verdicts where they change behavior — always-on rules, CONTEXT.md, reference examples. The kit's rule packs carry the stack's conventions; this skill extracts the project's own, which no pack can know.

It decides and codifies. Code changes (unification, deepening) route out.

Phase 0 — Load profile

1. Read .claude/PROJECT.md — Architecture, Conventions, Plans location. Missing or TEMPLATE → fall back to the root CLAUDE.md (always in context) when it carries those facts, proceeding on it and noting you're running without a kit profile; only if neither has them, STOP, run /bootstrap first.
2. Read the installed .claude/rules/* (generic + stack packs) — what's already codified is not re-mined; a mined pattern that contradicts an installed rule is a finding of its own (the rule is aspiration, the code is fact — the user decides which bends).
3. Read CONTEXT.md if present — patterns get named in the project's language.

Phase 1 — Mine (fan out)

Mine along dimensions, one finder agent per dimension over the scope (parallel, background; pass .claude/schemas/finding.schema.json for mergeable output):

error handling & propagation · construction/wiring (DI, factories, composition root) · how modules address each other (import shapes, layering idiom) · data access · validation placement · naming & file organization · test structure (arrange/act/assert idiom, fixtures, fakes-vs-mocks) · async/concurrency idiom · logging & observability · config access · dynamic dispatch & metaprogramming (verdict against rules/_generic/code.md: a declared, enumerable DSL seam is BLESS material; scattered runtime name-construction is BAN with the static replacement — registry table or committed codegen — named).

Each finder reports pattern candidates: a recurring shape with every occurrence cited path:line. The floor is 3 occurrences — below that it's an incident, not a convention (report 2-site near-patterns separately as "emerging", no verdict). For each candidate also report the counter-occurrences: sites doing the same job a different way. Frequency counts come from grep -c-style evidence, not impression.

Phase 2 — Verdict each pattern

Frequency describes; it does not prescribe. For each mined pattern, decide:

• BLESS — dominant and good: codify it. The best in-repo occurrence becomes the worked GOOD example.
• UNIFY — 2+ competing conventions for the same job (the fork tax: every reader and every generation pays it). Pick the winner with the user (AskUserQuestion), on evidence: which the stack rules favor, which the newer code uses, which is deeper per /codebase-design, migration cost each way. Codify the winner; route the migration of the loser's sites to /sweep.
• BAN — dominant but harmful: codify the replacement, never a bare prohibition — a ban without a named alternative just breeds a third variant. Route existing sites to /sweep (mechanical) or /arch-health (structural).
• DEEPEN — a copy-paste family: the same logic re-implemented with variations wants to be one deep module (/codebase-design). Route to /refactor (small, local) or /prepare (cross-cutting).

Intent gate before any BAN or UNIFY-against verdict (core.md: surprising code is load-bearing until proven decorative; your prior for "idiomatic" is the training mean, not this repo): check git log on representative sites and docs/adr/ for a reason the pattern is deliberate. A sanctioned exception — an ADR or a rule that blesses it — is intent, not rot: leave it, or route the disagreement to /revisit. Weird-but-consistent beats familiar-but-foreign.

Phase 3 — Install (with confirmation)

Nothing lands without the user confirming the batch. Placement follows /writing-skills' altitude call — always-on context is precious:

• Rule (.claude/rules/<name>.md, paths:-scoped frontmatter): the invariant only — a few imperative lines plus ONE GOOD / ONE BAD example taken from this repo (path cited). Must-apply-on-every-matching-edit things only.
• Reference skill (.claude/skills/<name>-conventions/SKILL.md, on-demand): the heavy version — many worked examples, edge cases — when the rule would otherwise bloat. Measure before splitting an existing rule this way. Fenced examples are usually a smaller share of a rule's weight than they look: measured across one project's heavy rules they were 5–16 %, so moving every one of them out bought ~10 KB off a 116 KB autoload — a split that costs two files, a link to keep true and a second place for the rule to drift from. Run the numbers on the actual files (bytes inside ``` fences ÷ total) and split only where the share is large. Prose, not examples, is what makes a rule heavy.
• CONTEXT.md via /domain-model: when the pattern names a domain concept.
• Scaffold / codemod: a BLESSed structural pattern may install as a committed generator template (greppable codegen, per rules/_generic/code.md — never runtime magic); a UNIFY/BAN verdict hands /sweep a ready codemod spec (the FROM → TO pair + suggested tool), not prose.
• Automation, when the convention is mechanically decidable: a rule a script, generator, or template can enforce belongs there, and the document shrinks to a pointer at the command — prose alone is not followed reliably, at any level of seniority. Then test the automation: silent partial failure is its failure mode.
• Report: Write the full inventory to the Plans location (<plans>/<YYYY-MM-DD>-distill.md) so verdicts survive the session (git policy per PROJECT.md → Artifact git policy).

Verify each installed rule's paths: glob actually matches the intended files (Glob it). Project-specific rules land in the project's rules/, never back into kit packs.

Output

## Pattern Inventory — <scope>

| Pattern | Dimension | Sites (for/against) | Verdict | Installed as | Route |

### Blessed & installed
- <pattern> — rule `rules/<name>.md` (exemplar: `path:line`)

### Unified (winner chosen)
- <job>: <winner> over <loser> (N vs M sites) — migration → /sweep

### Banned (replacement named)
- <pattern> → <replacement> — sites → /sweep | /arch-health

### Deepening candidates
- <family> (N variants) → /refactor | /prepare

### Emerging (< 3 sites, no verdict) · Contradictions with installed rules

Hard rules

• 3+ cited occurrences or it isn't a pattern. Every count grounded in search output.
• Frequency never auto-wins. Dominant-and-bad gets banned; the verdict is a decision, not a tally.
• Intent gate before banning. Check git history and ADRs; sanctioned exceptions stand (disagreement → /revisit).
• Every BAN names its replacement.
• Install only with confirmation, at the right altitude — lean always-on rules, heavy reference on-demand.
• Codify here, migrate elsewhere. Site changes go to /sweep / /refactor / /prepare — never applied in this skill.

Cross-reference

• /sweep — executes a UNIFY/BAN migration mechanically, with inventory + re-scan.
• /arch-health — hunts structural rot; this skill hunts conventional drift. Complementary periodic scans.
• /codebase-design — the depth vocabulary behind DEEPEN verdicts.
• /refactor — applies small deepenings; reads the rules this skill installs.
• /revisit — where a mined pattern collides with a recorded decision.
• /retro — folds process lessons into rules; this skill folds code patterns.
• /writing-skills — the rule-vs-skill altitude call Phase 3 follows.