Compound Md

Review CLAUDE.md from conversation history

Analyze recent conversations to improve both global (~/.claude/CLAUDE.md) and local (project) CLAUDE.md files.

• [ ] Step 1: Find conversation history
• [ ] Step 2: Extract recent conversations
• [ ] Step 3: Spin up Sonnet subagents
• [ ] Step 4: Score and filter findings
• [ ] Step 5: Walk user through findings one by one

Transcript auditor, not prose reviewer. You programmatically extract user messages, tool calls, and results from JSONL conversation logs, then spin up subagents to analyze behavior against CLAUDE.md rules.

Your role:

• Extract conversation data from JSONL files via jq
• Launch parallel subagents to analyze conversations against CLAUDE.md
• Score findings ruthlessly — CLAUDE.md is loaded into every context
• Present findings one at a time via AskUserQuestion for user review

Not your role:

• Editing CLAUDE.md directly (present findings, user decides)
• Reviewing the current session (skip most recent file)

Avoid:

• Processing the current session (always skip most recent JSONL)
• Swallowing jq errors to /dev/null
• Treating user messages as always string type (they can be arrays)
• Dropping tool_use blocks from assistant messages
• Presenting a wall of findings — use AskUserQuestion to walk through one at a time

Process

Step 1: Find Conversation History

The project's conversation history is in ~/.claude/projects/. The folder name is the project path with slashes replaced by dashes.

# Find the project folder (replace / with -)
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lt "$CONVO_DIR"/*.jsonl | head -20

Step 2: Extract Recent Conversations

Extract the 15-20 most recent conversations (excluding the current session) to a temp directory.

IMPORTANT: The jq filter contains != which zsh will escape/mangle when passed inline. Write the filter to a file first, then reference it with jq -r -f.

Step 2a: Write the jq filter to $SCRATCH/extract.jq:

if .type == "user" then
  .message.content |
  if type == "string" then
    "USER: " + .
  elif type == "array" then
    [ .[] |
      if .type == "text" then .text
      elif .type == "tool_result" then
        (.content |
          if type == "string" then .[0:100]
          elif type == "array" then
            [.[] | select(.type == "text") | .text[0:100]] | join(" ")
          else "" end
        ) | if . != "" then "RESULT: " + . else empty end
      else empty end
    ] | map(select(. != "")) | join("\n") |
    if . != "" then "USER:\n" + . else empty end
  else empty end
elif .type == "assistant" then
  [ .message.content // [] | .[] |
    if .type == "text" then .text
    elif .type == "tool_use" then
      "TOOL: " + .name + "(" + (.input | tostring | .[0:100]) + ")"
    else empty end
  ] | map(select(. != "")) | join("\n") |
  if . != "" then "ASSISTANT:\n" + . else empty end
else empty end

Step 2b: Run the extraction loop using the filter file:

SCRATCH=/tmp/claudemd-review-$(date +%s)
mkdir -p "$SCRATCH"

# Write the jq filter file first (Step 2a above)

# tail -n +2 skips the most recent file (current session)
for f in $(ls -t "$CONVO_DIR"/*.jsonl 2>/dev/null | tail -n +2 | head -20); do
  convo_id=$(basename "$f" .jsonl)
  jq -r -f "$SCRATCH/extract.jq" "$f" > "$SCRATCH/${convo_id}.txt" 2>>"$SCRATCH/debug.log"
done

ls -lhS "$SCRATCH"

Step 3: Spin Up Sonnet Subagents

Launch parallel Sonnet subagents to analyze conversations. Each agent should read:

• Global CLAUDE.md: ~/.claude/CLAUDE.md
• Local CLAUDE.md: ./CLAUDE.md (if exists)
• Batch of conversation files

Give each agent this prompt template:

Read:
1. Global CLAUDE.md: ~/.claude/CLAUDE.md
2. Local CLAUDE.md: [project]/CLAUDE.md
3. Conversations: [list of files]

Analyze the conversations against BOTH CLAUDE.md files. For each finding, output:

**Finding:** [one-line description]
**Type:** violated | add-local | add-global | outdated
**Evidence:** [specific conversation ID + what happened]
**Proposed change:** [exact wording to add, edit, or remove]
**Universality score (1-5):**
  5 = Will prevent bugs/waste in virtually every future session
  4 = Applies to most sessions in this project type
  3 = Applies sometimes, depends on task
  2 = Niche — only relevant for specific workflows
  1 = One-off incident, not a pattern
**Frequency:** [how many conversations exhibited this]

Be specific. Output structured findings only.

Batch conversations by size (smaller batches = more agents = better parallelism):

• Large (>100KB): 1 per agent
• Medium (10-100KB): 2 per agent
• Small (= 3, frequency > 1 or universality >= 4)
• [ ] Each surviving finding presented individually via AskUserQuestion
• [ ] User accepted/skipped each finding explicitly
• [ ] Summary of applied vs skipped changes shown at end

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.