reflect

## 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:
```python
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:
```bash
# 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:**
```json
{
  "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 project learnings"},
    {"content": "Deduplicate similar learnings", "status": "pending", "activeForm": "Removing duplicate learnings"},
    {"content": "Check existing CLAUDE.m