reflect

name	reflect
description	Analyze the current session and propose improvements to skills. **Proactively invoke this skill** when you notice user corrections after skill usage, or at the end of skill-heavy sessions. Also use when user says "reflect", "improve skill", or "learn from this".
allowed-tools	Read, Write, Edit, Grep, Glob, Task, Bash, AskUserQuestion

Reflect Skill

Analyze the current session and propose improvements to skills based on what worked, what didn't, and edge cases discovered.

Trigger

Run /reflect or /reflect [skill-name] after a session where you used a skill.

Additional commands:

• /reflect on - Enable automatic end-of-session reflection
• /reflect off - Disable automatic reflection
• /reflect status - Check if auto-reflect is enabled

Workflow

Step 1: Identify the Skill

If skill name not provided, ask:

Which skill should I analyze this session for?
- frontend-design
- code-reviewer
- [other]

Step 2: Analyze the Conversation

Look for these signals in the current conversation:

Corrections (HIGH confidence):

• User said "no", "not like that", "I meant..."
• User explicitly corrected output
• User asked for changes immediately after generation

Successes (MEDIUM confidence):

• User said "perfect", "great", "yes", "exactly"
• User accepted output without modification
• User built on top of the output

Edge Cases (MEDIUM confidence):

• Questions the skill didn't anticipate
• Scenarios requiring workarounds
• Features user asked for that weren't covered

Preferences (accumulate over sessions):

• Repeated patterns in user choices
• Style preferences shown implicitly
• Tool/framework preferences

Step 3: Propose Changes

Present findings using accessible colors (WCAG AA 4.5:1 contrast ratio):

┌─ Skill Reflection: [skill-name] ───────────────────┐
│                                                    │
│ Signals: X corrections, Y successes                │
│                                                    │
│ Proposed changes:                                  │
│                                                    │
│ 🔴 [HIGH] + Add constraint: "[specific constraint]"│
│ 🟡 [MED]  + Add preference: "[specific preference]"│
│ 🔵 [LOW]  ~ Note for review: "[observation]"       │
│                                                    │
│ Commit: "[skill]: [summary of changes]"            │
│                                                    │
└────────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

Accessible Color Palette (use ANSI codes in terminal output):

• HIGH: \033[1;31m (bold red #FF6B6B - 4.5:1 on dark)
• MED: \033[1;33m (bold yellow #FFE066 - 4.8:1 on dark)
• LOW: \033[1;36m (bold cyan #6BC5FF - 4.6:1 on dark)
• Reset: \033[0m

Avoid: pure red (#FF0000) on black, green on red (colorblind users)

User Response Options:

• Y – Apply changes, commit, and push
• n – Skip this update
• Or describe any tweaks to the proposed changes

Step 4: If Approved

1. Read the current skill file from .claude/skills/[skill-name]/SKILL.md
2. Apply the changes using the Edit tool
3. Run git commands:

   cd .claude/skills
   git add [skill-name]/SKILL.md
   git commit -m "[skill]: [change summary]"
   git push origin main
   

4. Confirm: "Skill updated and pushed to GitHub"

Step 5: If Declined

Ask: "Would you like to save these observations for later review?"

If yes, append to .claude/skills/[skill-name]/OBSERVATIONS.md

Toggle Commands

/reflect on

Enable automatic end-of-session reflection:

1. Create/update ~/.claude/reflect-skill-state.json with {"enabled": true, "updatedAt": "[timestamp]"}
2. Confirm: "Auto-reflect enabled. Sessions will be analyzed automatically when you stop."

/reflect off

Disable automatic reflection:

1. Update ~/.claude/reflect-skill-state.json with {"enabled": false, "updatedAt": "[timestamp]"}
2. Confirm: "Auto-reflect disabled. Use /reflect manually to analyze sessions."

/reflect status

Check current status:

1. Read ~/.claude/reflect-skill-state.json
2. Report: "Auto-reflect is [enabled/disabled]" with last updated timestamp

Note: The state file is saved in the global Claude user directory (~/.claude/) so it persists across plugin upgrades.

Example Session

User runs /reflect frontend-design after a UI session:

┌─ Skill Reflection: frontend-design ───────────────┐
│                                                   │
│ Signals: 2 corrections, 3 successes               │
│                                                   │
│ Proposed changes:                                 │
│                                                   │
│ 🔴 [HIGH] + Constraints/NEVER:                    │
│    "Use gradients unless explicitly requested"    │
│                                                   │
│ 🔴 [HIGH] + Color & Theme:                        │
│    "Dark backgrounds: use #000, not #1a1a1a"      │
│                                                   │
│ 🟡 [MED] + Layout:                                │
│    "Prefer CSS Grid for card layouts"             │
│                                                   │
│ Commit: "frontend-design: no gradients, #000 dark"│
│                                                   │
└───────────────────────────────────────────────────┘

Apply these changes? [Y/n] or describe tweaks

Git Integration

This skill has permission to:

• Read skill files from .claude/skills/
• Edit skill files (with user approval)
• Run git add, git commit, git push in the skills directory

The skills repo should be initialized at .claude/skills with a remote origin.

Important Notes

• Always show the exact changes before applying
• Never modify skills without explicit user approval
• Commit messages should be concise and descriptive
• Push only after successful commit