# Bpawlakj AI Devkit Rule Review

> Bpawlakj Ai Devkit Rule Review

- Skill: `tomevault-io/bpawlakj-ai-devkit-rule-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/bpawlakj-ai-devkit-rule-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bpawlakj-ai-devkit-rule-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

```bash
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|maybe|might|could)\b` | Weak verb — rewrite imperatively. |
| `\b(clean|good|quality|nice|elegant|maintainable|robust)\s+code\b` | Empty intent — rewrite as an observable behavior. |
| `\b(always|never|must|should)\s+(?!\s|$)` followed by a vague object | Decide if observable; if not, rewrite. |
| 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:

```bash
# 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:

```markdown
# 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 <path>." 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](https://github.com/bpawlakj/ai-devkit) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->