review-rules

name	review-rules
description	Review the core instruction layer — CLAUDE.md, .claude/rules/*.md, and RIPER/CAT mode definitions — for size, staleness, cross-reference integrity, alignment with active hooks, and redundancy. Creates board tasks for every finding.
disable-model-invocation	true
user-invocable	true

Rules & Core Instructions Review Protocol

Reviews the always-loaded instruction layer that governs every Claude Code session in this repo. Scope:

• CLAUDE.md (project root)
• .claude/rules/*.md
• .claude/settings.json hooks config (only to verify rule-hook alignment)

Part of the review-* skill family. Cites ../_shared/review-checklist.md and ../_shared/anthropic-configuration-guide.md.

Owner: docs-manager agent.

When to invoke

• CLAUDE.md approaching 150 lines (lean limit) or > 200 lines
• After significant process changes (new hooks, new RIPER modes, new deployment patterns)
• Quarterly audit
• When new team members or agents repeatedly make mistakes the rules should prevent

Output contract

Board tasks only. Lean summary to main agent.

---

Step 1 — Inventory

• Read CLAUDE.md. Record line count, section list, referenced rules/skills/docs/agents.
• Read every .claude/rules/*.md. Record line count, topic, referenced files.
• Read .claude/settings.json hooks block. Record which hooks exist and what they enforce.

Step 2 — Size discipline

Artifact	Target	Hard limit
CLAUDE.md	< 150 lines	200 lines
Individual rule	< 200 lines	300 lines

Flag bloat. Recommend:

• CLAUDE.md bloat → push detail into a new rule or existing rule
• Rule bloat → split by sub-topic or move deep reference to a skill / doc

Step 3 — Staleness

For each rule and for CLAUDE.md, check:

• Deprecated infrastructure references (Supabase Edge Functions, old table names, retired services)
• Domain names and URLs still current ( variants, MIG host IDs, LB IP <YOUR_LB_IP>)
• Model IDs match current Anthropic lineup (Opus 4.8, Sonnet 4.6, Haiku 4.5)
• Command references valid (Enter C -push-dev, Enter C -push, Enter C -all)
• Stripe API version current (2025-08-27.basil per CLAUDE.md)
• Referenced docs exist (every [link](path) resolves)
• Referenced agents exist in .claude/agents/
• Referenced skills exist in .claude/skills/

Step 4 — Cross-reference integrity

• Every [text](relative/path.md) in CLAUDE.md and rules → file exists (Glob)
• Every rule file → referenced from CLAUDE.md at least once (orphans are dead weight)
• Every rule topic → has an invocation pattern documented

Step 5 — Rule-hook alignment

Match the written rules against the behavior enforced by .claude/settings.json:

• Does agent-board.md describe hooks that actually exist?
• Does riper-cat.md describe auto-transitions that the Stop hook actually enforces?
• Does CLAUDE.md reference hooks that are live?
• Are there hooks in settings.json that no rule explains to humans?

Flag misalignments.

Step 6 — RIPER-CAT accuracy

Specifically for riper-cat.md:

• All 8 modes (R/I/P/E/RE/C/AI/T) described and mapped to the Enter signal
• Auto-transitions described match /plan and /review skill behavior
• COMMIT flags (-commit, -push, -push-dev, -all, -return) match rules/deployment.md
• Agent assignment rules cross-check with /plan skill + .claude/agents/ roster

Step 7 — Redundancy

For the ruleset as a whole:

• Content duplicated across rules (flag for consolidation)
• Content duplicated between CLAUDE.md and a rule (rule wins — pull from CLAUDE.md)
• Two rules that should be merged (near-duplicate scope)
• One rule that should be split (two unrelated topics joined)

Step 8 — Missing rules

Scan recent memory (MEMORY.md), recent commits, and recent incident logs for recurring patterns not yet codified as rules. Candidates:

• Ops patterns that caused repeat incidents
• Coding rules recently learned the hard way
• Deployment patterns not yet documented

Flag as "Codify pattern [X] as a rule".

Step 9 — File findings to the board

Create parent tasks per severity + subtasks on project <YOUR_AUDIT_PROJECT_ID>. Assigned agent: docs-manager.

Step 10 — Summary

Return ≤ 100 words:

RULES REVIEW COMPLETE
- CLAUDE.md: [N] lines (target <150)
- [X] rule files reviewed
- [C/H/M/L] findings per severity → board parent tasks
- [MR] missing-rule candidates
- [RA] redundancy/alignment issues

Anti-patterns to flag

• CLAUDE.md growing past 200 lines (must reduce)
• Rules that contradict each other
• Rule behavior described in CLAUDE.md but not enforced by hooks (drift risk)
• Dead links in CLAUDE.md or rules
• References to retired model IDs or deprecated commands
• Rules that have never been referenced (orphans)

Tools used

• Read, Glob, Grep
• Optionally: read .claude/settings.json to verify hook alignment
• Board MCP (create_task, update_task, log_activity)