/reflect

description: Reflect on session corrections and update CLAUDE.md (with human review)
allowed-tools: Read, Edit, Write, Glob, Bash, Grep, AskUserQuestion, TodoWrite

Arguments

• `--dry-run`: Preview all changes without prompting or writing.
• `--scan-history`: Scan ALL past sessions for corrections (useful for first-time setup or cold start).
• `--days N`: Limit history scan to last N days (default: 30). Only used with `--scan-history`.
• `--targets`: Show detected AI assistant config files and exit.
• `--review`: Show learnings with stale/decayed entries for review.
• `--dedupe`: Scan CLAUDE.md for similar entries and propose consolidations.
• `--organize`: Analyze memory hierarchy and suggest reorganization across tiers.
• `--include-tool-errors`: Include project-specific tool execution errors in scan (auto-enabled with `--scan-history`).
• `--model MODEL`: Model for semantic analysis (default: `sonnet`). Use `haiku` for faster/cheaper runs or `opus` for maximum accuracy.

Context

• Project CLAUDE.md: @CLAUDE.md
• Global CLAUDE.md: @~/.claude/CLAUDE.md
• Learnings queue (per-project): !`python3 "$(dirname "$(dirname "$(readlink -f "$0")")")/scripts/read_queue.py" 2>/dev/null || echo "[]"`
• Current project: !`pwd`

Multi-Target Export

Claude-reflect syncs learnings to CLAUDE.md files (including subdirectories), skill files, and AGENTS.md.

**Supported Targets:**

| Target | File Path | Format | Notes | |--------|-----------|--------|-------| | **Global CLAUDE.md** | `~/.claude/CLAUDE.md` | Markdown | Always enabled | | **Project CLAUDE.md** | `./CLAUDE.md` | Markdown | If exists | | **CLAUDE.local.md** | `./CLAUDE.local.md` | Markdown | Personal, gitignored | | **Subdirectory CLAUDE.md** | `./**/CLAUDE.md` | Markdown | Auto-discovered | | **Project Rules** | `./.claude/rules/*.md` | Markdown | Modular rules, optional path-scoping | | **User Rules** | `~/.claude/rules/*.md` | Markdown | Global modular rules | | **Skill Files** | `./commands/*.md` | Markdown | When correction relates to skill | | **Auto Memory** | `~/.claude/projects/<project>/memory/*.md` | Markdown | Low-confidence, exploratory learnings | | **AGENTS.md** | `./AGENTS.md` | Markdown | Industry standard (Codex, Cursor, Aider, Jules, Zed, Factory) |

**Target Discovery:**

Use the Python utility to find all memory tier files:

from scripts.lib.reflect_utils import find_claude_files
files = find_claude_files()
# Returns list of {path, relative_path, type, frontmatter}
# Types: 'global', 'root', 'local', 'subdirectory', 'rule', 'user-rule'

Or discover manually:

# Find all CLAUDE.md files (excluding node_modules, .git, venv, etc.)
find . -name "CLAUDE.md" -type f \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  -not -path "*/venv/*" \
  -not -path "*/.venv/*"
# Also check rule files and local
ls .claude/rules/*.md 2>/dev/null
ls CLAUDE.local.md 2>/dev/null
ls ~/.claude/rules/*.md 2>/dev/null

**Target Selection (Hierarchy-Aware Routing):**

• **Guardrail corrections** ("don't do X") → `.claude/rules/guardrails.md`
• **Model preferences** → existing model-preferences rule file or `~/.claude/CLAUDE.md`
• **Global behavioral** (always/never/prefer) → `~/.claude/CLAUDE.md`
• **Path-scoped** (learning mentions directory covered by rule's `paths:`) → that rule file
• **Personal/local** (machine-specific, not for team) → `./CLAUDE.local.md`
• **Low-confidence** (0.60-0.74) → auto memory for later promotion
• **Project-specific** → `./CLAUDE.md` or subdirectory file
• Let users override routing with AI reasoning

**Note on Confidence & Decay:**

• Confidence scores help prioritize learnings during `/reflect` review
• Decay applies to **queue items only** — if a learning sits unprocessed for too long, it's flagged as stale
• Once applied to CLAUDE.md, entries are permanent (edit manually to remove)

Your Task

MANDATORY: Initialize Task Tracking (Step 0)

**BEFORE starting any work**, use TodoWrite to create a task list for the entire workflow. This ensures no steps are skipped and provides visibility into progress.

**Why this is critical:**

• The /reflect workflow has 10+ phases that must execute in order
• Without tracking, Claude may skip steps or lose context
• TodoWrite acts as a checkpoint system ensuring completeness

**Initialize with this task list (adjust based on arguments):**

TodoWrite tasks for /reflect:
1. "Parse arguments and check flags" (--dry-run, --scan-history, etc.)
2. "Load learnings queue from ~/.claude/learnings-queue.json"
3. "Scan historical sessions" (if --scan-history)
4. "Validate learnings with semantic analysis"
5. "Filter by project context (global vs project-specific)"
6. "Deduplicate similar learnings"
7. "Check for duplicates in existing CLAUDE.md"
8. "Present summary and get user decision"
9. "Apply changes to CLAUDE.md/AGENTS.md"
10. "Clear queue and confirm completion"

**Workflow rules:**

• **Mark in_progress BEFORE starting each step** - this signals what's happening
• **Mark completed IMMEDIATELY after finishing** - don't batch updates
• **Only ONE task should be in_progress at a time**
• **Never skip a step** - if a step doesn't apply, mark it completed with a note
• **If blocked or error occurs**, keep task as in_progress and create a new task for the blocker

**Example TodoWrite call at start:**

{
  "todos": [
    {"content": "Parse arguments (--scan-history detected)", "status": "in_progress", "activeForm": "Parsing command arguments"},
    {"content": "Load learnings queue", "status": "pending", "activeForm": "Loading queue from ~/.claude/learnings-queue.json"},
    {"content": "Scan historical sessions", "status": "pending", "activeForm": "Scanning past sessions for corrections"},
    {"content": "Validate with semantic analysis", "status": "pending", "activeForm": "Validating learnings semantically"},
    {"content": "Filter by project context", "status": "pending", "activeForm": "Filtering global vs projec