# Reflect > Captures learnings after feature completion for future agent reference Use when this capability is needed. - Skill: `tomevault-io/reflect-11` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/reflect-11` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/reflect-11/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/reflect-11 --- # Reflect Skill ## Purpose This skill captures learnings, patterns, gotchas, and decisions after a feature is complete. Reflections are stored in `.agent/memory/reflections/` and indexed for future agent queries. Based on the [Reflection Loop](https://arxiv.org/abs/2303.11366) pattern for iterative improvement through self-feedback. ## When to Invoke - After `@code-review` approves the implementation - After a feature is merged - After resolving a significant bug or issue - When explicitly asked to document learnings ## Prerequisites - Feature implementation is complete - Code review has passed - Spec exists at `specs//spec.md` ## Workflow ### Step 1: Gather Context Collect information about the completed feature: 1. Read the spec: `specs//spec.md` 2. Read the plan: `specs//plan.md` 3. Read self-critique report (if exists) 4. Review git commits for the feature 5. Note any issues or discussions ### Step 2: Generate Reflection Create a reflection document answering: 1. **What was built?** (1-2 sentence summary) 2. **What worked well?** (patterns, approaches) 3. **What were the gotchas?** (unexpected issues) 4. **What decisions were made?** (and why) 5. **What would you do differently?** (hindsight) ### Step 3: Extract Tags Identify tags for indexing: - Domain tags: `plates`, `topology`, `persistence` - Pattern tags: `event-sourcing`, `snapshot`, `encoding` - Tool tags: `rocksdb`, `messagepack`, `modernsatsuma` ### Step 4: Save Reflection Write to `.agent/memory/reflections/.md` ### Step 5: Update Index Auto-update `.agent/memory/reflections/index.md` with: - New entry in the table - Tags added to tag sections - Key learnings summary ## Reflection Template ```markdown # Reflection: **Date:** YYYY-MM-DD **Spec:** `specs//spec.md` **Tags:** `tag1`, `tag2`, `tag3` ## Summary [1-2 sentence description of what was built] ## What Worked Well - **[Pattern/Approach]**: [Why it worked] - **[Pattern/Approach]**: [Why it worked] ## Gotchas & Edge Cases - **[Issue]**: [What happened and how it was resolved] - **[Issue]**: [What happened and how it was resolved] ## Decisions Made ### [Decision Title] - **Decision:** [What was decided] - **Alternatives:** [What was considered] - **Rationale:** [Why this choice] ## What I'd Do Differently - [Hindsight observation] ## Related - RFC: [link] - ADR: [link] - Related reflections: [links] ``` ## Index Format The index at `.agent/memory/reflections/index.md` is auto-maintained: ```markdown # Reflections Index ## Recent Reflections | Feature | Date | Tags | Key Learning | |---------|------|------|--------------| | [feature](./feature.md) | 2026-01-23 | tags | One-liner | ## By Tag ### plates - [feature-1](./feature-1.md) - summary - [feature-2](./feature-2.md) - summary ### persistence - [feature-1](./feature-1.md) - summary ``` ## Querying Reflections Future agents can query reflections: ``` @reflect --query "plates topology" @reflect --query "rocksdb gotchas" @reflect --list-tags ``` The skill will search the index and return relevant reflections. ## Example Reflection ```markdown # Reflection: plate-topology-snapshots **Date:** 2026-01-20 **Spec:** `specs/plate-topology-snapshots/spec.md` **Tags:** `plates`, `persistence`, `snapshots`, `rocksdb` ## Summary Implemented head-only snapshot persistence for plate topology using RocksDB, storing the materializer state as MessagePack-encoded blobs. ## What Worked Well - **Separation of snapshot vs event storage**: Keeping snapshots in a separate column family made compaction independent and queries fast. - **MessagePack for large blobs**: Significantly smaller than JSON, faster to encode/decode for topology graphs. ## Gotchas & Edge Cases - **ModernSatsuma handle serialization**: Initially tried to serialize node handles directly. Had to create stable ID mapping first, then serialize the ID-based representation. - **Batch size limits**: RocksDB write batches over 100MB caused memory pressure. Added chunking for large snapshots. ## Decisions Made ### Head-only vs Full History - **Decision:** Store only head snapshot, not full history - **Alternatives:** Store all snapshots, store periodic checkpoints - **Rationale:** Events provide full history; snapshots are optimization for fast reload. Head-only is simplest and sufficient. ## What I'd Do Differently - Would have designed the ID mapping layer first before touching ModernSatsuma serialization. ## Related - RFC: RFC-V2-0004-rocksdb-eventstore-and-snapshots.md - ADR: ADR-0005-use-modern-rocksdb-for-db-first-persistence.md ``` ## Checklist - [ ] Reflection captures all key learnings - [ ] Tags are relevant and consistent with existing tags - [ ] Index is updated - [ ] Related specs/RFCs are linked - [ ] Gotchas are actionable for future agents --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/giantcroissant-lunar) — claim your Tome and manage your conversions.