extract-conventions

The convention-extraction organ. Auto-populates the project rule tier. Gates on the rule-prime hook for its output to be load-bearing — without the hook priming the extracted file, it is an inert surface. Feeds naming-and-comments, whose audit cites the project-tier conventions this writes.

Extract observes a scope and makes its implicit, tacit conventions explicit — a durable artefact the rule-prime hook primes and /review audits, rather than stateless per-run re-inference that is drift-prone and points a reviewer at nothing.

When to run

• User types /extract-conventions <scope> (or with no arg → prompt for scope).
• Natural language: "capture this module's conventions", "extract our house style", "codify how this codebase names things".
• Do not auto-fire. Mode A, user-invoked only. Extracting and writing a project-tier rule is a deliberate act, never a session side effect. No hook, no session-start trigger.

Inputs

• Scope argument — a directory (src/auth/), a module, or a language (csharp). With no arg, prompt:

  What scope should I extract conventions from? A directory (src/auth/), a module, or a language (csharp).

• Working directory — $CLAUDE_PROJECT_DIR or cwd. Anchors the write target (<project>/.claude/rules/...) and the rule-overlay resolution.
• Per-category accept/edit/reject decisions — collected at the confirm gate (§4). Collaborator principle — never auto-write.

Procedure

1. Resolve scope and sample

Resolve the scope argument to a concrete file set:

Consume the scope-resolution resolver where shipped for the boundary/granularity model; degrade to language-level when it isn't present. Do not invent a competing granularity model.

Sampling. For large scopes, sample representatively rather than reading everything — newest + largest + a spread across subdirectories, capped at ~30 files / ~6000 lines. Record which files were sampled; the evidence lists in the report cite them. A convention observed in only 1–2 files is not "dominant" — require a real majority before reporting one.

If the scope resolves to zero source files, stop:

Scope <scope> has no source files to sample. Check the path or language.

2. Detect mechanical conventions (deterministic)

Run detect.mjs over the sampled files. It frequency-analyzes mechanical conventions — the ones a machine can count without judgment:

• Case style per identifier kind (types, methods/properties, fields, locals, constants) — PascalCase / camelCase / snake_case / SCREAMING_SNAKE, with the dominant style and its share.
• Field prefixes — m_, _, s_, none — measured over data fields only (methods/properties/locals don't idiomatically carry a prefix, so including them dilutes the signal), with the dominant prefix and its share.
• Import / using ordering — grouped-then-alphabetical, alphabetical, unordered.
• Indentation — tabs vs spaces, width.
• Brace style — same-line vs next-line (where the language allows both).

For each detected convention, detect.mjs returns { category, convention, dominant, share, confidence, evidence: [files] }. Confidence is high when the dominant share is ≥ ~80% across a real sample; medium for a 60–80% plurality; below that the convention is not dominant and is dropped (reported as "no dominant convention" for that axis, not invented).

The determinism is the point: the same scope yields the same mechanical report every run. This is what done-criterion #2 means by "detected deterministically" — and why this half is a script, not a model judgment.

3. Detect semantic conventions (model judgment, confidence-flagged)

For semantic conventions a counter can't capture, judge from the sampled files — but honestly (an audit is complete only for the classes it actually checked):

• Comment style / density — doc-comment presence on public surface, inline-comment density, comment voice (terse vs explanatory).
• Error-handling idiom — exceptions vs result types, guard-clause vs nested, how failures are surfaced.
• Test conventions — naming, arrange/act/assert structure, fixture style (when tests are in scope).

Every semantic convention is explicitly labelled lower-confidence and presented under a heading distinct from the deterministic ones. Never present an inferred convention as observed fact. State what was actually seen ("18 of 22 sampled public methods have an XML doc comment") and let the share carry the claim — do not assert a convention an absent pattern would contradict. If a semantic axis shows no clear pattern, say so; do not manufacture one.

4. Per-category propose-confirm-commit gate

Present detected conventions grouped by the four categories — naming / comments / organization / idioms — each with evidence and confidence. Deterministic (high/medium) conventions and inferred (lower-confidence) conventions are visually separated:

## Detected conventions for <scope> (sampled N files)

### Naming  [deterministic]
- Types: PascalCase (high — 47/47 sampled)            evidence: Foo.cs, Bar.cs, …
- Members: m_ prefix + camelCase (high — 41/44)       evidence: Foo.cs, Baz.cs, …
- Locals: camelCase (high — 120/126)                  evidence: …

### Comments  [inferred — lower confidence]
- Public methods carry XML doc comments (medium — 18/22 observed)   evidence: …
- Inline comments are terse, why-not-what (inferred)               evidence: …

### Organization  [deterministic]
- One type per file (high — 47/47)                    evidence: …
- using directives grouped System-first then alpha (high)         evidence: …

### Idioms  [inferred — lower confidence]
- Guard-clause error handling, no nested try (inferred — observed in 9/12)   evidence: …

Then gate per category:

For each category — accept / edit / reject? Naming: (a)ccept / (e)dit / (r)eject Comments: (a)ccept / (e)dit / (r)eject Organization: (a)ccept / (e)dit / (r)eject Idioms: (a)ccept / (e)dit / (r)eject

• accept → the category's conventions go into the file.
• edit → user revises the wording / drops a line; apply their revision.
• reject → the category is omitted entirely.

Nothing is written until at least one category is accepted. Rejecting all categories writes no file and ends the run with "No conventions accepted — nothing written." This is the standard propose-confirm-commit pattern: never auto-write.

5. Conflict surfacing vs shipped universal rules

Before writing, resolve the accepted conventions against the rule overlay (the shipped universal tier in particular). For each accepted convention, check whether it contradicts a shipped rule — e.g. an m_ member-prefix convention against universal/naming.md's no-prefix stance, or a next-line brace style against a shipped same-line rule.

When a contradiction is found, surface it at confirm time using the contradicts / override-with-note pattern:

⚠ The accepted convention members use m_ prefix contradicts the shipped rule universal/naming ("no Hungarian / member prefixes"). Writing this convention will override the shipped rule for <scope>. (o)verride-with-note — write the convention; record relations: [contradicts: universal/naming] + a one-line note (d)rop — keep the shipped rule; omit this convention (k)eep-both — write the convention without the override note (not recommended; the overlay will still resolve project-tier-wins, but the divergence won't be auditable)

Default to override-with-note on explicit user choice — the file never silently shadows a shipped rule. The note + contradicts relation is recorded in the rule file for a future reviewer.

6. Author the conventions prose (language-pro delegated)

The skill owns strategy — what to extract, the confidence assessment, the gate, the conflict check (all above). The idiomatic writing of the conventions prose for a given language dispatches to the scope's language-pro agent (c-sharp-pro, cpp-pro, rust-pro, react-pro, …) where one exists for the scope's language.

Dispatch protocol — positive scope, hard placement, no recursion:

• Positive scope + hard placement, never a "do NOT" fence. The prompt states exactly what to produce: "Write the body of a conventions.md architectural-rule for this project's C# code. Here are the accepted, evidenced conventions: <list>. Render them as terse, model-readable rule bullets in idiomatic C# terminology. Output only the rule body — no frontmatter, no preamble."
• No further spawn — the language-pro agent is a leaf; it must not dispatch again (recursion cap).
• Pass the accepted conventions + evidence, not the raw files — the agent writes prose from the settled convention list, it does not re-detect.
• When no language-pro agent exists for the scope's language, the skill authors the prose itself in the same terse rule-bullet style — delegation is an idiom-quality optimization, not a hard dependency.

The returned prose is the body of the conventions file. The skill validates it is rule-shaped (terse bullets, no invented conventions beyond the accepted list) before writing.

7. Write to the project rule tier

Write the accepted, authored conventions to the project rule tier:

• Default granularity: per-language — <project>/.claude/rules/<lang>/conventions.md.
• Refinable to per-module — when the user requests it (or a subtree genuinely diverges from the language default), write the deeper-scoped override at <project>/.claude/rules/<lang>/<module>/conventions.md or the module path the scope-resolution model resolves. Ask before writing a per-module file when the scope was a directory that maps to one.

Frontmatter (the rule frontmatter format):

---
name: <Lang> conventions (<scope>)
description: <one-line — the dominant conventions captured>
type: project
kind: architectural-rule
scope: [<lang>, <scope-tags>]
relevance: when-touching-<lang>
relations:                         # only when a conflict was overridden in §5
  - type: contradicts
    target: architectural-rules/universal/naming.md
    note: <one-line — project uses m_ prefix; overrides shipped no-prefix stance>
---

relevance: when-touching-<lang> (or when-touching-<module> for a per-module file) — scoped, not always, so it primes only when the scope is in play and does not bloat the always-tier floor.

Never overwrite an existing project-tier conventions.md blind. If one exists for the target scope, show the diff and confirm — or, if the user is refreshing after drift, treat the existing file as a baseline and surface what changed.

Report the write:

Wrote <project>/.claude/rules/<lang>/conventions.md (N conventions across M categories). With the rule-prime hook active, this primes into context when you touch <lang> and overrides the universal defaults for this scope. /review audits against it.

8. Stop

Do not invoke /review, do not commit. The written file is the user's to commit. Do not auto-run /extract-conventions again. The conform half is not this skill's job — it is the emergent payoff of the rule-prime hook priming the file + /review auditing against it.

More in reference.md: What extract-conventions does NOT do, relationship to other organs, debug.