@az9713/claude-md-doctor

---
name: claude-md-doctor
description: Audit and improve CLAUDE.md files. Use when rules aren't working, context is bloated, or after learning a lesson that should become a rule.
disable-model-invocation: true
---

# CLAUDE.md Doctor

Audit, diagnose, and improve CLAUDE.md files for this project.

## Usage

- `/claude-md-doctor` or `/claude-md-doctor audit` — Full audit of all CLAUDE.md files
- `/claude-md-doctor add-rule <description>` — Add a new rule based on a lesson learned

## Audit Procedure

When invoked with `audit` or no arguments:

### Step 1: Discover All CLAUDE.md Files

Search for CLAUDE.md files at all levels:
- Project root: `./CLAUDE.md`
- Subdirectories: `./**/CLAUDE.md`
- User-level: `~/.claude/CLAUDE.md`

Report which files exist and their line counts.

### Step 2: Check Structure Against Best Practices

A well-structured CLAUDE.md should have these sections (in order of importance):

1. **What** — Project architecture overview (what this project IS)
2. **Domain** — Tech stack, key dependencies, language/framework conventions
3. **Validation** — Build, test, and lint commands (the verification loop)
4. **Critical Rules** — Never/always rules that prevent recurring mistakes

Check for each section. Report missing sections as warnings.

### Step 3: Analyze Health Metrics

- **Line count**: Warn if >200 lines (bloat risk — Claude loads this into every context)
- **Duplicate rules**: Flag rules that say the same thing in different words
- **Stale references**: Flag mentions of files/paths that don't exist
- **Vague rules**: Flag rules without concrete actions (e.g., "write clean code" — too vague)
- **Missing validation loop**: Critical warning if no build/test/lint commands are defined

### Step 4: Check Git Status

Run `git status CLAUDE.md` to check if the file is:
- Tracked and committed (good)
- Modified but uncommitted (warn: team won't see changes)
- Untracked (warn: not shared with team)

### Step 5: Generate Report

Output a structured report:

```
## CLAUDE.md Health Report

### Files Found
- ./CLAUDE.md (N lines) [committed/uncommitted/untracked]
- ./src/CLAUDE.md (N lines) [committed/uncommitted/untracked]

### Section Coverage
- [x] What (architecture)
- [ ] Domain (tech stack) — MISSING
- [x] Validation (build/test/lint)
- [ ] Critical Rules — MISSING

### Warnings
- Line count: N (target: <200)
- Duplicate rules found: ...
- Stale path references: ...

### Recommendations
1. Add a "Domain" section describing...
2. Add a "Critical Rules" section with...
```

## Add Rule Procedure

When invoked with `add-rule <description>`:

### Step 1: Parse the Lesson

Read the `$ARGUMENTS` after `add-rule` to understand what lesson was learned.

### Step 2: Formulate the Rule

Convert the lesson into a concrete, actionable rule:
- Start with "Always" or "Never"
- Be specific (mention files, commands, patterns)
- Include the WHY (so future Claude instances understand the reason)

Example: "Never use `rm -rf` on the build directory — use `make clean` instead, which preserves the cache"

### Step 3: Add to CLAUDE.md

- If a "Critical Rules" section exists, append the rule there
- If not, create the section at the end of the file
- Format as a bullet point

### Step 4: Confirm

Show the user the exact rule added and its location.