Reflect Skill

HIGH Priority Triggers (Invoke Immediately)

MEDIUM Priority Triggers (Invoke After Multiple)

LOW Priority Triggers (Invoke at Session End)

Original Triggers (Still Supported)

When to Use

Use this skill when:

• User corrects your output ("no", "wrong", "not like that")
• User praises specific output ("perfect", "exactly")
• Edge cases are discovered during work
• Session end after skill-heavy work
• Want to capture learnings before they are lost

Use retrospective instead when:

• Conducting a full session retrospective (broader scope)
• Analyzing multi-session patterns across the project

Proactive Invocation Reminder

Don't wait for users to ask! Invoke reflect immediately when you detect:

1. User says "no" - Invoke reflect NOW (captures correction)
2. User says "perfect" - Invoke reflect NOW (captures success pattern)
3. User asks "what if" - Invoke reflect NOW (captures edge case)
4. You used multiple skills - Invoke reflect at END (captures all learnings)
5. User corrected your output - Invoke reflect IMMEDIATELY (critical learning)

Why this matters: Without proactive reflection, learnings are LOST. The Stop hook captures some patterns, but manual reflection is MORE ACCURATE because you have full conversation context.

Cost: ~30 seconds of analysis. Benefit: Prevents repeating mistakes forever.

Process

Phase 1: Identify the Target Skill

Locate the skill-based memory to update:

1. Check Brain memories: Search for observation notes via mcp__plugin____brain__search({ query: "{skill-name} observations" })
2. Infer from context: Identify which skill(s) were used in the conversation
3. Create if needed: If missing, propose {skill-name}-observations note in the skills/ folder

Storage: Brain MCP (canonical) via mcp__plugin____brain__write_note to the skills/ folder

Phase 2: Analyze the Conversation

Scan the conversation for learning signals with confidence levels:

HIGH Confidence: Corrections

User actively steered or corrected output. These are the most valuable signals.

Detection patterns:

• Explicit rejection: "no", "not like that", "that's wrong", "I meant"
• Strong directives: "never do", "always do", "don't ever"
• Immediate requests for changes after generation
• User provided alternative implementation
• User explicitly corrected output format/structure

Example:

User: "No, use the PowerShell skill script instead of raw gh commands"
> [HIGH] + Add constraint: "Use PowerShell skill scripts, never raw gh commands"

MEDIUM Confidence: Success Patterns

Output was accepted or praised. Good signals but may be context-specific.

Detection patterns:

• Explicit praise: "perfect", "great", "yes", "exactly", "that's it"
• Implicit acceptance: User built on top of output without modification
• User proceeded to next step without corrections
• Output was committed/merged without changes

Example:

User: "Perfect, that's exactly what I needed"
> [MED] + Add preference: "Include example usage in script headers"

MEDIUM Confidence: Edge Cases

Scenarios the skill didn't anticipate. Opportunities for improvement.

Detection patterns:

• Questions skill didn't answer
• Workarounds user had to apply
• Features user asked for that weren't covered
• Error handling gaps discovered

Example:

User: "What if the file doesn't exist?"
> [MED] ~ Add edge case: "Handle missing file scenario"

LOW Confidence: Preferences

Accumulated patterns over time. Need more evidence before formalizing.

Detection patterns:

• Repeated choices in similar situations
• Style preferences shown implicitly (formatting, naming)
• Tool/framework preferences
• Workflow preferences

Example:

User consistently uses `-Force` flag
> [LOW] ~ Note for review: "User prefers -Force flag for overwrites"

Confidence Threshold

Only propose changes when sufficient evidence exists:

Phase 3: Propose Learnings

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

+-------------------------------------------------------------+
| SKILL REFLECTION: {skill-name}                              |
+-------------------------------------------------------------+
|                                                             |
| [HIGH] + Add constraint: "{specific constraint}"            |
|   Source: "{quoted user correction}"                        |
|                                                             |
| [MED]  + Add preference: "{specific preference}"            |
|   Source: "{evidence from conversation}"                    |
|                                                             |
| [MED]  + Add edge case: "{scenario}"                        |
|   Source: "{question or workaround}"                        |
|                                                             |
| [LOW]  ~ Note for review: "{observation}"                   |
|   Source: "{pattern observed}"                              |
|                                                             |
+-------------------------------------------------------------+
| Apply changes? [Y/n/edit]                                   |
+-------------------------------------------------------------+

Color Key (accessible):

• [HIGH] - Red/bold: Mandatory corrections (user explicitly said "no")
• [MED] - Yellow/amber: Recommended additions
• [LOW] - Blue/dim: Notes for later review

User Response Handling:

On rejection (n):

1. Log that reflection was declined (for future pattern analysis)
2. Ask user if they want to revise the analysis or skip entirely
3. If skip, end workflow without memory update

On edit:

1. Present first finding with options: [keep/modify/remove]
2. If modify, accept user's revised text
3. Repeat for each finding
4. Confirm final list before applying

Phase 4: Persist Learnings to Memory

ALWAYS show changes before applying.

After user approval:

1. Read existing memory (if exists) via mcp__plugin____brain__read_note
2. Append new learnings with timestamp and session reference
3. Preserve existing content - never remove without explicit request
4. Extract code citations (Phase 4 Enhancement - see below)
5. Write to Brain: mcp__plugin____brain__write_note or mcp__plugin____brain__edit_note

Storage: Brain MCP (canonical) - write observation notes to the skills/ folder with the naming pattern SKILL-{NNN}-{skill-name}-observations.md

Memory Format:

# Skill Sidecar Learnings: {Skill Name}

**Last Updated**: {ISO date}
**Sessions Analyzed**: {count}

## Constraints (HIGH confidence)

- {constraint 1} (Session {N}, {date})
- {constraint 2} (Session {N}, {date})

## Preferences (MED confidence)

- {preference 1} (Session {N}, {date})
- {preference 2} (Session {N}, {date})

## Edge Cases (MED confidence)

- {edge case 1} (Session {N}, {date})
- {edge case 2} (Session {N}, {date})

## Notes for Review (LOW confidence)

- {note 1} (Session {N}, {date})
- {note 2} (Session {N}, {date})

Phase 4 Enhancement: Auto-Citation Capture

When persisting learnings that reference specific code locations, automatically capture citations:

1. Detect code references in learning text:

   • Inline code references: `path/to/file.ext` line N
   • Function references: `functionName()` in `file.ext`
   • Explicit citations: "See: file.ext:42"

2. Extract citation metadata: file path, line number, snippet (if available)

3. Add citations to Brain note as observations with [fact] category

4. Update confidence score based on initial verification

Detection Patterns:

Decision Tree

User says "reflect" or similar?
|
+--> YES
|   |
|   +--> Identify skill(s) used in conversation
|   |   |
|   |   +--> Skill identified?
|   |       |
|   |       +--> YES -> Analyze conversation for signals
|   |       |   |
|   |       |   +--> Meets confidence threshold?
|   |       |       |
|   |       |       +--> YES -> Present findings, await approval
|   |       |       |   |
|   |       |       |   +--> User says Y -> Update Brain memory
|   |       |       |   |
|   |       |       |   +--> User says n -> Ask for feedback
|   |       |       |   |   |
|   |       |       |   |   +--> User wants revision -> Re-analyze
|   |       |       |   |   +--> User skips -> End workflow
|   |       |       |   |
|   |       |       |   +--> User says edit -> Interactive review
|   |       |       |       |
|   |       |       |       +--> Per-finding [keep/modify/remove]
|   |       |       |
|   |       |       +--> NO -> Report "Insufficient evidence. Note for next session."
|   |       |
|   |       +--> NO -> Ask user which skill to reflect on
|   |           |
|   |           +--> User specifies skill -> Continue with that skill
|   |           +--> User says "none" -> End workflow
|   |
|   +--> Multiple skills?
|       |
|       +--> Analyze each, group findings by skill, present together
|
+--> NO -> This skill not invoked

Examples

Example 1: Correction Detected

Conversation:
User: "Create a PR for this change"
Agent: [runs gh pr create directly]
User: "No, use the github skill script!"

Analysis:
[HIGH] + Add constraint: "Always use .claude/skills/github/ scripts for PR operations"
  Source: User correction - "No, use the github skill script!"

Example 2: Success Pattern

Conversation:
User: "Add error handling"
Agent: [adds try/catch with specific error types]
User: "Perfect! That's exactly what I wanted"

Analysis:
[MED] + Add preference: "Use specific error types in catch blocks, not generic [Exception]"
  Source: User approval after seeing specific error types

Example 3: Edge Case Discovery

Conversation:
User: "Run the build"
Agent: [runs build command]
User: "Wait, what if the node_modules folder doesn't exist?"

Analysis:
[MED] + Add edge case: "Check for node_modules existence before build"
  Source: User question about missing dependencies

Use Cases

1. Code Review Skills

Capture learnings about code review patterns:

• Style guide rules: User corrections on formatting, naming, structure
• Security patterns: Security vulnerabilities caught, OWASP patterns enforced
• Severity levels: When issues are P0 vs P1 vs P2
• False positives: Patterns that look like issues but aren't

2. API Design Skills

Track API design decisions:

• Naming conventions: REST endpoint patterns, verb choices
• Error formats: HTTP status codes, error response structure
• Auth patterns: OAuth, JWT, API key patterns
• Versioning style: URL versioning, header versioning

3. Testing Skills

Remember testing preferences:

• Coverage targets: Minimum % required, critical paths
• Mocking patterns: When to mock vs integration test
• Assertion styles: Preferred assertion libraries, patterns
• Test naming: Convention for test method names

4. Documentation Skills

Learn documentation patterns:

• Structure/format: Section order, heading levels
• Code examples: Real vs pseudo-code, language choice
• Tone preferences: Formal vs casual, active vs passive voice
• Diagram styles: Mermaid vs ASCII, detail level

Anti-Patterns

Integration

With Session Protocol

Run reflection at session end as part of retrospective:

## Session End Checklist
- [ ] Complete session log
- [ ] Run skill reflection (if skills were used)
- [ ] Update Brain memory
- [ ] Commit changes

With Brain Memory

Skill memories integrate with the Brain memory system:

# Search skill sidecar learnings
mcp__plugin____brain__search({ query: "github observations constraints" })

# Read specific skill sidecar
mcp__plugin____brain__read_note({ identifier: "SKILL-001-github-observations" })

Verification

Design Decisions

Agent Sidecar Naming: {skill-name}-observations

Decision: Skill memories follow the Brain note pattern (e.g., SKILL-001-github-observations.md).

Rationale:

• Reuses the Brain entity type convention instead of inventing a parallel structure
• Keeps {domain}-{description} format while making "skill-sidecar" explicit
• Discovery via Brain search prevents orphaned learnings
• Single Canonical Store: Brain MCP writes to the knowledge graph, eliminating dual-governance ambiguity

Relationship to curating-memories

• curating-memories = general-purpose maintenance of any memory artifact (linking, pruning, marking obsolete).
• reflect = targeted retrospective that feeds those artifacts with new learnings.
• When a sidecar accumulates conflicting guidance, route the file to curating-memories for cleanup.

Session Protocol Integration

• Add "Run skill reflection if >=3 distinct skills used" to the Session End checklist.
• Document any manual edits in the session log before completion.
• Invoke reflect immediately after the Stop hook highlights high-confidence learnings so the session log and sidecar stay in sync.

Extension Points

1. Curating memories - route conflicting or stale learnings to curating-memories for consolidation.
2. Memory skill - use memory skill for search/recall before proposing redundant learnings.
3. Session log fixer - after reflection, ensure the session log captures the learning summary via session-log-fixer.

Related

Commit Convention

When committing skill observation updates:

chore(memory): update {skill-name} skill sidecar learnings (session {N})

- Added {count} constraints (HIGH confidence)
- Added {count} preferences (MED confidence)
- Added {count} edge cases (MED confidence)
- Added {count} notes (LOW confidence)

Session: {session-id}