reflect

Reflect - Self-Improving Skills

What This Does

Captures session learnings and proposes updates to skill files, closing the loop between "Claude makes a mistake → You correct it → Same mistake next session."

Who It's For

Ed and any vibe coder who wants their AI assistant to actually learn from corrections.

The Problem It Solves

LLMs don't learn from us. Every conversation starts from zero. This skill bridges that gap by turning corrections into persistent skill updates.

Instructions

Manual Mode (Default)

When user says "reflect", "/reflect", "what did we learn", or "update skills from this session":

1. Scan the conversation for:

   • Explicit corrections ("Never do X", "Always do Y", "Change this to...")
   • Approvals ("That's perfect", "Yes, like that", repeated patterns that worked)
   • Failed attempts that were fixed
   • New patterns discovered

2. Classify each finding by confidence:

   • HIGH: Explicit corrections from user ("Never make up button styles")
   • MEDIUM: Patterns that worked well without explicit approval
   • LOW: Observations worth noting but not confirmed

3. Classify by topic (for routing):

   Topic	Target
   Universal workflow rule	CLAUDE.md
   Obsidian, Templater, daily notes	.claude/rules/obsidian.md
   External APIs (Basecamp, Substack, Gemini)	.claude/rules/api-integrations.md
   Skill/agent building, settings	.claude/rules/skill-development.md
   Image generation, carousels	.claude/rules/image-generation.md
   Git operations, file safety	.claude/rules/git-safety.md
   Agent/skill instruction patterns	.claude/rules/agent-patterns.md
   Skill-specific pattern	The skill's SKILL.md or docs/

   The test: "Does this apply to EVERY session?" Yes → CLAUDE.md. No → rules/ or skill docs.

4. For HIGH confidence findings:

   • Identify the target file using topic classification
   • Propose a specific edit (show old → new)
   • Generate commit message

5. Present findings to user:

   ## Session Learnings
   
   ### HIGH Confidence (Propose Immediate Update)
   - [Finding 1] → Update skill: [skill-name]
     Proposed change: [specific edit]
   
   ### MEDIUM Confidence (Consider Adding)
   - [Finding 2] → Could update: [skill-name]
   
   ### LOW Confidence (Note for Later)
   - [Observation]
   
   Approve changes? [Yes / Modify / Skip]
   

6. On approval:

   • Edit the skill file
   • Commit with message: reflect: [summary of learning]
   • Confirm completion

Automatic Mode (Future - via Hook)

When enabled via stop hook, automatically run reflection at session end:

• Only commit HIGH confidence findings
• Show notification of what was updated
• Log to session summary

Examples

Example 1: Explicit Correction

User said during session:

"Never use emojis in code comments. I hate that."

Reflect proposes:

HIGH Confidence Finding:
- Rule: No emojis in code comments
- Topic: Universal workflow rule (applies to ALL sessions)
- Target: CLAUDE.md
- Proposed addition to Iron Rules:
  + 4. **NO EMOJIS IN CODE.** Unless explicitly requested.

Commit message: reflect: Add no-emojis rule to Iron Rules

Approve? [Yes / Modify / Skip]

Example 2: Pattern Discovery

User repeatedly approved same format:

Session shows: User approved 3 research docs all using same header structure

Reflect proposes:

MEDIUM Confidence Finding:
- Pattern: Research docs use ## Executive Summary first
- Relevant skill: research-swarm agent
- Suggested note: "Always start research docs with Executive Summary section"

Add to Notes & Learnings? [Yes / Skip]

Guidelines

• Only propose changes for HIGH confidence findings without explicit approval
• MEDIUM and LOW findings require user confirmation before any edits
• Never overwrite existing rules without showing the change
• Prefer adding to existing skills over creating new ones
• Commit messages always start with reflect: prefix

Commands

Version History

Notes & Learnings

• Initial build based on Ras Mic's YouTube video approach
• Start with manual mode to validate workflow before adding hooks
• Confidence levels prevent over-eager updates

TODO (Implementation)

• Test manual /reflect workflow
• Add hook configuration for automatic mode
• Create tools/reflect.sh for hook integration
• Add to CLAUDE.md workflow documentation