reflect

Type	Skill
Plugin	awl-general · v0.0.51
Invoke	/awl-general:reflect
Tools	Read, Edit, Glob, Write, Grep
Source	plugins/awl-general/skills/reflect/SKILL.md

When Claude uses it

Session retrospective — reviews for learnings and persists rules to CLAUDE.md or cross-session patterns to auto-memory. Use when user says “reflect”, “what did we learn”, “save learnings”, “session review”, or “remember this for next time”. Do NOT use for one-off questions or mid-task work.

Trigger phrases: reflect · what did we learn · save learnings · session review · remember this for next time

Definition

Session retrospective: find learnings — especially user corrections — and persist them for future sessions.

Key distinction: Claude’s built-in auto-memory captures individual feedback moments as they happen. This skill adds value by doing a session-wide retrospective that catches patterns, repeated corrections, and rules that should be promoted to CLAUDE.md.

Step 1: Scan Existing Persistence

Before reviewing the session, read what’s already persisted to avoid duplicates:

1. Read ./CLAUDE.md (project) and ~/.claude/CLAUDE.md (global) — skip if either doesn’t exist
2. Discover the auto-memory directory: Glob ~/.claude/projects/*/memory/MEMORY.md — find the entry matching the current project’s working directory
3. Read MEMORY.md index and scan memory file names — if no memory directory exists yet, create it when applying (Step 6)

Step 2: Review Session

Scan the conversation for:

1. User corrections (highest priority) — where user told Claude to do something differently
   • Wrong tool or approach chosen
   • Wrong assumptions about codebase
   • Style/convention mismatches
   • Unnecessary work or over-engineering
2. Cross-session patterns — conventions, commands, workflows that emerged and will recur
3. Gotchas — non-obvious issues encountered and resolved

For each, note:

• What happened (one line)
• What the correct behavior should be (one line)

Step 3: Categorize

Route each learning to the right persistence layer:

Category	What belongs here	Target	Format
Rule	Hard behavioral rules, conventions Claude must follow	./CLAUDE.md (project) or ~/.claude/CLAUDE.md (global)	Bullet point under appropriate section
Pattern	Cross-session context, project knowledge, domain patterns	Auto-memory memory/ directory	Frontmatter file (see format below)

What goes where

• CLAUDE.md = instructions that change Claude’s behavior (“always do X”, “never do Y”, “use Z command for builds”)
• Auto-memory = context that informs decisions (“project uses FactoryKit for DI”, “user prefers closure-based dismiss over @Environment”)

Auto-memory file format

---
name: <descriptive name>
description: <one-line — used to decide relevance in future conversations>
type: <user | feedback | project | reference>
---

<content — for feedback/project: lead with rule, then **Why:** and **How to apply:** lines>

After creating/updating a memory file, update MEMORY.md index with a link and brief description.

What NOT to persist (auto-memory already handles these)

• Individual in-the-moment corrections (auto-memory captures these live)
• Code patterns derivable from reading the codebase
• Git history or recent changes
• Debugging solutions (the fix is in the code)

Step 4: Triage

For each learning, apply ALL filters. Discard if any is true:

• One-off? (unlikely to recur)
• Already documented? (found in Step 1)
• Cosmetic? (doesn’t change Claude’s behavior)
• Obvious? (any competent developer would know this)
• Already captured by auto-memory this session?

Keep if:

• Would have prevented a mistake in this session
• Will recur in future sessions
• Changes how Claude should behave

Be aggressive — fewer high-quality learnings > many low-value ones. Max 5-7 per session.

Step 5: Present

Show the user a summary table:

| # | Learning | Category | Target |
|---|----------|----------|--------|
| 1 | <one-line description> | Rule | ./CLAUDE.md |
| 2 | <one-line description> | Pattern | memory/feedback_foo.md |

Then show proposed diffs for each:

### 1. <learning title>
**Why:** <one-line reason this matters>
**Target:** <file path>

\`\`\`diff
+ <the addition — keep it to 1-2 lines>
\`\`\`

Step 6: Apply with Approval

Ask which items to apply (all, some, none).

For each approved item:

1. Read the target file (already done in Step 1, but re-read if needed)
2. Find the appropriate section (or create one if needed)
3. Apply via Edit tool (prefer appending to existing sections)
4. For memory files: create with frontmatter format above, update MEMORY.md index

Format rules:

• One line per learning where possible
• Use existing section structure in target files
• No verbose explanations — brevity is critical (these are prompt context)
• Use backticks for commands, bold for emphasis

Anti-patterns

Do NOT:

• Add generic best practices (“write clean code”)
• Duplicate info already in CLAUDE.md or existing memory files
• Add session-specific context (task details, file names from this task only)
• Create new sections when an existing one fits
• Modify skills — skill updates should be deliberate, not a side-effect of reflection
• Write memory content directly into MEMORY.md (it’s an index, not a memory)