Reflect

Reflect Skill

Critical learning capture system that prevents repeating mistakes and preserves successful patterns across sessions.

Analyze the current conversation and propose improvements to skill-based memories based on what worked, what didn't, and edge cases discovered. Every correction is a learning opportunity - invoke proactively to build institutional knowledge.

Triggers

Three priority tiers drive invocation timing: HIGH (corrections and immediate fixes, invoke immediately), MEDIUM (praise, preferences, edge cases, and questions, invoke when the table threshold is met), LOW (repeated patterns and session-end consolidation). Invoke proactively, not only on explicit request.

See references/triggers.md for the full priority-tiered trigger tables, the original trigger phrases, and the proactive-invocation reminder.

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

Process

Phase 1: Identify the Target Skill

Locate the skill-based memory to update:

1. Check Serena memories: Look for files ending with -observations.md in .serena/memories/
2. Infer from context: Identify which skill(s) were used in the conversation
3. Create if needed: If missing, propose {skill-name}-observations.md (skill observations pattern)

Storage Locations:

• Serena MCP (canonical): .serena/memories/{skill-name}-observations.md via mcp__serena__write_memory
• Contingency (Serena unavailable): Manually edit the same file in Git and note the manual update in the per-issue handoff for later Serena sync

Phase 2: Analyze the Conversation

Scan the conversation for learning signals at three confidence levels: HIGH (corrections), MEDIUM (success patterns, edge cases), and LOW (preferences). Only propose changes when the confidence threshold is met (>=1 HIGH, >=2 MED, or >=3 LOW signals).

See references/phase2-signal-detection.md for the full detection patterns per confidence level and the threshold table.

Phase 3: Propose Learnings

Present findings in a confidence-labeled summary ([HIGH]/[MED]/[LOW] with the source quote for each), then await user approval (Y/n/edit). Always show changes before applying.

Phase 4: Persist Learnings to Memory

After approval: read existing memory, append new learnings with timestamp and session reference, preserve existing content, extract code citations, and write to .serena/memories/{skill-name}-observations.md (Serena MCP canonical; Git fallback when Serena is unavailable).

See references/phase3-4-propose-persist.md for the proposal display format, user-response handling, persistence strategy, memory format, and the Phase 4 auto-citation capture.

Decision Tree, Examples, and Anti-Patterns

See references/decision-tree-and-examples.md for the full invocation decision tree, worked examples (correction, success pattern, edge case), per-domain use cases (code review, API design, testing, documentation), and the anti-patterns table.

Integration, Design Decisions, and Commit Convention

See references/integration-and-design.md for integration with the session protocol, the memory skill, and Serena; the design-decision rationale (sidecar naming, the Serena sidecar contract, relationship to curating-memories); extension points; and the commit convention for skill observation updates.

Verification

Related