Bpawlakj AI Devkit Rule Review

/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>

Step 2: Dimension 2 — embedded code / config blocks

For each fenced code block, measure lines.

Cite line ranges for each finding.

Step 3: Dimension 3 — language precision

Run regex / heuristic over each rule line:

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).

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).

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:

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:

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:

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.

Source: bpawlakj/ai-devkit — distributed by TomeVault.