---
name: review-claudemd
description: >
  Review recent conversations to improve project CLAUDE.md.
  USE WHEN user says "review claudemd", "update claudemd", "improve instructions",
  "setup-memory", "what should I add to claudemd".
---

# Review CLAUDE.md

Analyze recent conversation history to find improvements for the project CLAUDE.md.

## Routing

| User says | Action |
|-----------|--------|
| "review claudemd", "update claudemd", "improve instructions" | Full review workflow below |
| "setup-memory" | Same as above |
| "what should I add to claudemd" | Same as above |

## Step 1: Find Conversations

Locate JSONL session files. The project folder in `~/.claude/projects/` is the project's absolute path with `/` replaced by `-`:

```bash
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lt "$CONVO_DIR"/*.jsonl 2>/dev/null | head -20
```

If the path contains spaces or special characters and `sed` fails, use Python instead:

```bash
python3 -c "
import os
project_dir = os.path.join(os.path.expanduser('~/.claude/projects'), '-' + os.getcwd().replace('/', '-').lstrip('-'))
print(project_dir)
"
```

Take the **15–20 most recent** files that contain actual conversation messages (skip files with only `file-history-snapshot` entries).

List what you found:
```
Found N conversations (date range: YYYY-MM-DD to YYYY-MM-DD)
```

## Step 2: Extract Conversation Text

Use this Python script via Bash to extract user/assistant text from session files. Replace `CONVO_DIR` with the path from Step 1.

```bash
python3 -c "
import json, sys, os, glob
from datetime import datetime

base = os.path.join(os.path.expanduser('~/.claude/projects'), '-' + os.getcwd().replace('/', '-').lstrip('-')) + '/'
files = sorted(glob.glob(base + '*.jsonl'), key=os.path.getmtime, reverse=True)

MAX_SESSIONS = 20
MAX_CHARS_PER_SESSION = 8000
sessions_found = 0

for fpath in files:
    if sessions_found >= MAX_SESSIONS:
        break
    texts = []
    char_count = 0
    has_messages = False
    with open(fpath) as f:
        for line in f:
            obj = json.loads(line)
            role = obj.get('type', '')
            if role not in ('user', 'assistant'):
                continue
            has_messages = True
            content = obj.get('message', {}).get('content', '')
            if isinstance(content, str):
                if content.strip():
                    texts.append(f'[{role}] {content.strip()}')
                    char_count += len(content)
            elif isinstance(content, list):
                for block in content:
                    bt = block.get('type', '')
                    if bt != 'text':
                        continue
                    txt = block.get('text', '').strip()
                    if not txt:
                        continue
                    if '<system-reminder>' in txt:
                        clean = txt.split('<system-reminder>')[0].strip()
                        if clean:
                            texts.append(f'[{role}] {clean}')
                            char_count += len(clean)
                        continue
                    texts.append(f'[{role}] {txt}')
                    char_count += len(txt)
            if char_count >= MAX_CHARS_PER_SESSION:
                break
    if not has_messages:
        continue
    sessions_found += 1
    session_id = os.path.basename(fpath).replace('.jsonl', '')
    mtime = os.path.getmtime(fpath)
    date = datetime.fromtimestamp(mtime).strftime('%Y-%m-%d')
    output = '\n'.join(texts)
    if len(output) > MAX_CHARS_PER_SESSION:
        output = output[:MAX_CHARS_PER_SESSION] + '\n[...truncated]'
    print(f'=== SESSION {session_id} ({date}) ===')
    print(output)
    print()
"
```

## Step 3: Analyze with Subagents

First, read the current instructions:
- `CLAUDE.md` (project root)
- `.claude/rules/*.md` (all rule files)

Then launch **Sonnet subagents** (via Task tool, `subagent_type: "general-purpose"`, `model: "sonnet"`) to analyze the conversations. Batch **4–5 conversations per subagent**.

Each subagent prompt should include:
1. The full text of CLAUDE.md and rules files
2. The batch of conversation extracts
3. Instructions to return **structured JSON** with three categories:

```json
{
  "violated": [
    {
      "rule": "Which CLAUDE.md instruction was violated",
      "example": "Brief quote or description from conversation",
      "session": "session_id",
      "suggestion": "How to clarify or strengthen the rule"
    }
  ],
  "additions": [
    {
      "pattern": "What recurring pattern was observed",
      "example": "Brief evidence from conversations",
      "sessions": ["session_ids"],
      "suggested_rule": "Proposed text to add to CLAUDE.md"
    }
  ],
  "outdated": [
    {
      "rule": "Which CLAUDE.md instruction seems outdated",
      "evidence": "Why it appears outdated based on conversations",
      "suggestion": "Remove, update, or replace with..."
    }
  ]
}
```

**Subagent instructions:** Look for patterns like:
- User correcting Claude's behavior (suggests a missing/unclear rule)
- Claude doing something the rules say not to do (violated rule)
- Rules that never come up or contradict actual usage (outdated)
- Repeated user preferences not captured in CLAUDE.md
- Workflow patterns that should be documented

## Step 4: Report

Aggregate results from all subagents. Deduplicate findings (same rule/pattern across sessions).

Present as **three markdown tables**:

### Rules Violated

| Rule | Example | Sessions | Suggestion |
|------|---------|----------|------------|
| ... | ... | ... | ... |

### Suggested Additions

| Pattern | Evidence | Sessions | Suggested Rule |
|---------|----------|----------|----------------|
| ... | ... | ... | ... |

### Potentially Outdated

| Rule | Evidence | Suggestion |
|------|----------|------------|
| ... | ... | ... |

If a category has no findings, show: *"No findings in this category."*

## Step 5: Ask Before Editing

**Mandatory confirmation.** Never edit CLAUDE.md without asking.

Present options:
1. **Apply all** — make all suggested changes
2. **Pick individually** — go through each finding one by one
3. **Skip** — don't edit, optionally save report

If user picks **Apply all** or **Pick individually**:
- Make edits to CLAUDE.md using the Edit tool
- Show a summary of what changed

If user picks **Skip**:
- Offer to save the report as a note

## Edge Cases

- **Few conversations (<5):** Proceed but note limited data: *"Only N sessions found — results may be incomplete."*
- **No conversations:** Report it and exit: *"No conversation history found for this project."*
- **Empty sessions:** Already filtered out in Step 2
- **No findings:** *"No issues found! Your CLAUDE.md looks well-aligned with actual usage."*