rule-review

name	rule-review
description	Audit an existing agent-rules file (AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, .github/instructions/*.md) across seven dimensions and emit a verdict per finding with concrete evidence. Goes beyond length / embedded code / language precision / redundancy / order (which 10x covers) by adding (6) cross-tool drift detection when multiple rules files exist for the same scope, and (7) dead-rule check that greps the codebase for the patterns each rule targets — if nothing matches, the rule may be obsolete. Cites the ai-devkit rule in ~/.claude/rules/ that already covers redundant content. Read-only by default; --fix applies safe rewrites (remove redundancy, split oversized rules, reorder by importance). Trigger phrases: "review AGENTS.md", "audit my CLAUDE.md", "check my rule file", "rule review", "is my AGENTS.md any good".
argument-hint	<path-to-rules-file> [--fix]
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob","AskUserQuestion"]

/rule-review — Audit a Rules File With Evidence

This skill reads an agent-rules file (any common format) and emits a structured audit across seven dimensions. Each finding cites concrete evidence: a line number, a file path, a ~/.claude/rules/ reference, a grep result, or a contradicting file. By default it's read-only — it diagnoses but doesn't change anything. With --fix, it applies safe rewrites.

Built on findings from Lulla et al. (well-used AGENTS.md → −28% time / −16% tokens) and Gloaguen et al. (redundant or LLM-generated rule files → +20–23% cost). The dimensions exist because each one is a documented failure mode in those evaluations.

When to use, when to skip

Use when:

• You just authored or edited AGENTS.md / CLAUDE.md and want a sanity check before committing.
• You inherited a project and the rules file feels bloated or unanchored.
• The agent keeps ignoring or misapplying a rule — review checks whether the rule is even reachable.
• You suspect drift between multiple rules files (root vs nested, AGENTS.md vs CLAUDE.md, vs .github/copilot-instructions.md).

Skip when:

• The file is the empty / one-line shim (e.g. CLAUDE.md containing only @AGENTS.md). Review the canonical file it points to instead.
• You're authoring from scratch — use /agents-md first; come back here for the audit after.
• The file is auto-generated by a tool that doesn't expect human review (e.g. CI-generated AGENTS.md).

Relationship to other skills

• /agents-md — upstream. Authors the file this skill audits. Steps 4–5 of /agents-md already apply the test-of-inclusion and size budget; this skill verifies the result against the broader dimension list.
• ~/.claude/rules/*.md — read-only reference. Findings cite specific rules from this layer when flagging redundancy.
• docs/reference/lessons.md — read-only reference. Findings citing "no Why:" propose deriving the reason from a matching lessons entry.

Output language

The audit report and any --fix rewrites to the target file are written in English, regardless of the user's chat language. This matches the global policy in ~/.claude/CLAUDE.md §13. Interactive prompts during the audit may use the user's working language; the persisted findings and fixed file content are always English.

The seven dimensions

1. Length — file size vs ~200-line guideline. Too long ⇒ U-shaped attention drops middle content; rule #47 on line 320 is rarely applied.
2. Embedded code or config blocks — fenced ... blocks longer than ~10 lines, or full config snippets pasted in. These belong in referenced files, not rules.
3. Language precision — vague verbs ("ensure", "consider", "try to"), intent-language without behavior ("write clean code"), abstract nouns ("good design"). Each should be rewritten as an observable, falsifiable rule.
4. Redundancy with auto-active layer — content already in ~/.claude/rules/*.md (when ai-devkit's rules layer is installed) or in publicly trained model knowledge. Each redundant rule cites the source that already covers it.
5. Order — important rules in the middle (low-attention zone). Critical rules should be at top; references at the bottom.
6. Cross-tool drift (beyond 10x) — when more than one rules file exists for the same scope (AGENTS.md + CLAUDE.md + .github/copilot-instructions.md + .cursor/rules/*.mdc), check that they don't contradict. Drift creates a coin-flip for the agent.
7. Dead rules (beyond 10x) — for each rule that targets a code pattern (file naming, import style, framework idiom), grep the codebase. If nothing matches the pattern the rule enforces or forbids, the rule may be obsolete and should be flagged.

Initial Response

When invoked:

1. Path given (/rule-review AGENTS.md): jump to Step 1.
2. No path: glob the repo for rule files. List candidates in order of likelihood:

Which file to audit?

  - AGENTS.md                                   (root, 187 lines)
  - CLAUDE.md                                   (root, 1 line, imports AGENTS.md)
  - src/api/AGENTS.md                           (nested, 42 lines)
  - .cursor/rules/api.mdc                       (Cursor)
  - .github/copilot-instructions.md             (Copilot)

Pass: /rule-review <path>

Then STOP.

Process

Step 0: Read and parse

Read the target file FULLY. Strip the YAML frontmatter (if any). Split into:

• Headings (#, ##, ###) — used for the order check (Dimension 5).
• Bulleted lists — typical rule format.
• Numbered lists — typical procedural rule format.
• Paragraphs — usually intro / connective tissue.
• Fenced code blocks — flagged for Dimension 2.

Print summary: Parsed: <N> headings, <M> rules, <K> code blocks, total <L> lines.

Step 1: Dimension 1 — length

wc -l <file>

Lines	Verdict	Note
≤ 150	OK
151–200	WARN	At the recommended ceiling. Consider splitting area-specific content.
201–300	FAIL	Over guidance. Recommend split. List the largest sections.
> 300	FAIL (critical)	Strongly over. Middle of file is in low-attention zone.

Step 2: Dimension 2 — embedded code / config blocks

For each fenced code block, measure lines.

Block size	Verdict	Action
1–10 lines	OK if it's an inline example	Keep.
11–25 lines	WARN	Extract to a referenced file, leave a pointer (> See: docs/reference/<file>).
> 25 lines	FAIL	Definitely extract. Inline blob is a context tax.

Cite line ranges for each finding.

Step 3: Dimension 3 — language precision

Run regex / heuristic over each rule line:

Pattern	Flag
`\b(consider	try to
`\b(clean	good
`\b(always	never
Sentence with no verb in present tense	Likely descriptive, not prescriptive — rewrite.

For each flagged line, emit a finding with verdict: WARN and a one-line rewrite suggestion.

Step 4: Dimension 4 — redundancy with auto-active layer

If ~/.claude/rules/*.md exists, read each. Build a topic index (typescript.md → ["unknown over any", "Zod validation", ...]).

For each rule line in the target file, attempt match:

• Keyword overlap (case-insensitive substring match on 3+ tokens).
• Same enforcement (allow / deny patterns matching).

Match	Verdict
Exact or near-exact ai-devkit coverage	FAIL — cite ~/.claude/rules/<file>.md line. Rule should be removed.
Partial overlap	WARN — cite, ask user to decide.
No match in auto-active layer, but it's a mainstream framework idiom (e.g. "use React hooks not class components")	WARN — model knowledge probably covers it; ask if it's local-specific.
Local-specific (anchored in docs/, lessons.md, an incident)	OK.

If ~/.claude/rules/ is missing, the redundancy check is skipped with a note: "ai-devkit rules layer not installed at ~/.claude/rules/ — Dimension 4 partial."

Step 5: Dimension 5 — order

U-shaped attention: top and bottom of long contexts are best attended; middle is weakest. If the file is > 100 lines, the critical rules should be in the top third.

Heuristic for "critical": rules tagged by the user with **critical**, **must**, (critical), or appearing under a ## Critical heading. If no explicit tagging, infer from content (e.g. access-control, destructive-operation gates, irreversible-action rules).

Order	Verdict
Critical rules all in top third	OK
Critical rules in middle third	WARN — propose reorder.
Critical rules in bottom third or scattered	FAIL — propose reorder. Print suggested section sequence.

Step 6: Dimension 6 — cross-tool drift (beyond 10x)

Check sibling files for the same scope:

# at the same directory level as target
ls AGENTS.md CLAUDE.md .github/copilot-instructions.md .cursor/rules/*.mdc 2>/dev/null

For each pair of files present:

Pair	Allowed shape	Drift check
AGENTS.md + CLAUDE.md (shim)	CLAUDE.md is one-line @AGENTS.md import OR symlink	If CLAUDE.md has its own rules → FLAG; either consolidate into AGENTS.md or split scopes explicitly.
AGENTS.md + .github/copilot-instructions.md	Copilot shim points to / mirrors AGENTS.md	If Copilot file has rules diverging from AGENTS.md, list the differences.
AGENTS.md + .cursor/rules/*.mdc	Cursor rules are area / glob-scoped, AGENTS.md is repo-wide	If Cursor rule restates a repo-wide AGENTS.md rule, flag redundancy.

For each drift finding, print the conflicting lines side by side:

DRIFT — error response shape
  AGENTS.md:42         "Errors return { error: { code, message, context } }."
  copilot-instructions:18  "Errors return { error: string }."
  Suggested fix: align both to AGENTS.md (the canonical one), or split scopes.

Step 7: Dimension 7 — dead rules (beyond 10x)

For each rule that targets a code pattern, attempt a grep:

Rule pattern	Grep
"Use absolute imports @/..."	grep -rEn "from ['\"]@/" --include='*.ts' --include='*.tsx'
"All migrations live in db/migrations/"	test -d db/migrations && ls db/migrations
"Use the formatDate() helper, not new Date().toISOString()"	grep -rEn "new Date\\(\\)\\.toISOString" --include='*.ts' (occurrences = signal that the rule is being violated, not that it's dead)
"Class components are prohibited"	grep -rEn "class \\w+ extends (React\\.)?Component" --include='*.tsx' (zero hits across a year-old repo ⇒ probably no longer relevant)

Grep result	Verdict
Pattern is referenced widely in code	OK (rule is alive)
Pattern is rare but present	OK
Pattern is absent from the entire codebase	WARN — possibly obsolete. Ask the user.
Pattern is forbidden + still present (rule is failing!)	FAIL — surface the violating files.

Skip rules that are not pattern-grep-able (workflow rules, business decisions). Note them in the report as "not grep-checkable".

Step 8: Emit the report

Print a single audit report:

# Rule audit — <path>
Audited: <YYYY-MM-DD>  Total lines: <N>  Rules parsed: <M>

## Verdict summary

| Dimension | Verdict | Findings |
|---|---|---|
| 1. Length | OK / WARN / FAIL | … |
| 2. Embedded blocks | OK / WARN / FAIL | … |
| 3. Language precision | OK / WARN / FAIL | <N> lines flagged |
| 4. Redundancy | OK / WARN / FAIL | <N> redundant w/ ai-devkit |
| 5. Order | OK / WARN / FAIL | … |
| 6. Cross-tool drift | OK / WARN / FAIL | <N> divergences |
| 7. Dead rules | OK / WARN / FAIL | <N> patterns absent |

## Findings

<one entry per finding, with: dimension, line range, verdict, evidence, suggested rewrite>

If invoked with --fix, jump to Step 9. Otherwise, STOP after the report and offer:

Actions you can take:
  - Re-author from scratch: /agents-md <scope>
  - Apply safe auto-fixes only: /rule-review <file> --fix
  - Edit manually and re-audit

Step 9: --fix mode (opt-in only)

Apply only safe rewrites — never destructive:

Finding type	Auto-fixable?	Action
Redundant with ~/.claude/rules/ (FAIL)	YES	Remove the rule, leave a <!-- removed: covered by ~/.claude/rules/<file>.md --> marker.
Oversized code block (FAIL)	NO	Print the extraction path that should be created; do not auto-extract.
Wrong order (critical in middle)	YES	Reorder sections: critical → conventions → workflow → references.
Vague verb (WARN)	NO	Print suggested rewrite; user applies.
Drift between files (FAIL)	NO	Print diff; user resolves.
Dead rule (WARN)	NO	Mark with <!-- candidate: obsolete, no codebase matches as of <date> -->.

Backup the original to <path>.bak-YYYYMMDD-HHMMSS before applying changes. Print the diff after applying.

Re-emit the audit report against the fixed file. Verify dimensions improved before declaring done.

Edge cases

• File doesn't exist: print "No file at ." Offer to delegate to /agents-md to author one.
• File is only the YAML frontmatter / empty body: trivial OK; nothing to audit.
• File is for an entirely different tool format (e.g. raw JSON config like .cursor/rules/*.mdc with non-markdown body): apply only dimensions 1, 5, 6 (length, order, cross-tool). Skip the rest with a note.
• Multiple files passed (/rule-review AGENTS.md CLAUDE.md): audit each in turn, then run Dimension 6 across all of them as a single pass.
• ~/.claude/rules/ is gigantic and dimension-4 matching is slow: tolerate; cache the topic index in memory for the session.