Reflection Skill

Purpose

Improve future Claude Code sessions by learning from mistakes and user corrections. Updates skill files in the target project's .claude/skills/ directory.

This is a meta-skill - it modifies other skills based on session learnings.

When to Run (Explicit Triggers Only)

Only activate when the user explicitly requests reflection:

• •"reflect"
• •"don't do this again"
• •"remember this for next time"
• •"update your skills"
• •"learn from this"

Never run automatically - always wait for explicit user trigger.

Where Rules Go

Rules are written to the target project's skill files (NOT the plugin repository):

If the target project doesn't have .claude/skills/, create it with a starter structure.

Process

1. •

   Analyse the completed session

   • •Review conversation for corrections
   • •Identify repeated mistakes
   • •Note stated preferences
2. •

   Extract atomic, durable rules

   • •One rule per concept
   • •"Do X" or "Never Y" format
   • •Date-stamped for tracking
3. •

   Check for contradictions

   • •Read existing skill files
   • •Flag conflicting rules
   • •Ask user to resolve
4. •

   Update appropriate skill file(s)

   • •Append to ## Learned Rules section
   • •Preserve existing formatting
   • •Keep changes minimal
5. •

   Commit changes separately from code

   • •Use semantic commit message
   • •Include rule summary in body

Rule Quality Bar

A rule must be:

• •Durable: Will apply to future work in this project
• •Actionable: Clear imperative ("Always X", "Never Y")
• •Specific: Not too broad or vague
• •Non-contradicting: Doesn't conflict with existing rules

Rule Format

- [YYYY-MM-DD] RULE_TEXT (source: BRIEF_CORRECTION_CONTEXT)

Examples:

- [2025-01-09] Always eager load relationships in service methods that return collections (source: booking service review)
- [2025-01-09] Never use axios - use Inertia router instead (source: corrected 3x in dashboard component)
- [2025-01-10] Use FloatingLabelInput for all form fields (source: user preference stated)

Starter Skill Structure

When creating .claude/skills/ in a new project:

# Lessons Learned

## Purpose
Project-specific rules learned from Claude Code sessions.

## Learned Rules
<!-- Reflection appends here -->

Git Commit Format

chore(skills): reflect session learnings

- Added: [rule summary]
- Source: [correction context]
- File: .claude/skills/[filename].md

What NOT to Learn

Do not create rules for:

• •One-time exceptions
• •User's momentary preferences
• •Context-specific decisions
• •Temporary workarounds

Only learn patterns that should always apply.