# Reflect > End-of-session reflection that proposes updates to CLAUDE.md / SOP.md / PROJECT-CONTEXT.md based on what happened. Use when the user asks to reflect on a session, capture lessons, propose CLAUDE.md updates, or invokes /tandem:reflect. The blog's "stop hooks reflect on what happened and propose CLAUDE.md updates" recommendation, implemented as a manual skill (less noisy than an auto-firing Stop hook that triggers on every trivial session). - Skill: `data-ai-xyz/reflect` (Agent Skill) - Install (CLI): `npx skillmds@latest add data-ai-xyz/reflect` - Raw SKILL.md: https://api.skillmd.com/api/skills/data-ai-xyz/reflect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: DATA-AI-XYZ (https://skillmd.com/u/data-ai-xyz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/data-ai-xyz/reflect --- # Tandem: reflect (self-improvement) Use at the end of a substantive session (>30 min of real work) to capture lessons that should bleed back into the kit's rules. The blog's "self-improvement loop" pattern. ## Ground the scan in the ledger first Before scanning from memory, read what the run **recorded at the time**. The retro ledger holds one line per development boundary — the friction, the kit signals and the estimate-vs-actual calls each close-out wrote as it happened — and recalling those is stronger evidence than reconstructing them at the end of a long session: ```bash node _00-Project-Management/93-Scripts/retro-report.js --month ``` Read the **current month only** — that is the in-flight view this skill needs, and the ledger grows monotonically, so loading all of it would cost more than it is worth here. This is `93-Scripts/retro-report.js`, the same aggregator `close-phase` and `monthly-retro` read: `reflect` does not re-implement the join, so the three surfaces cannot disagree about what happened. **An empty window changes nothing about this skill.** The output says `No retro records for this window.`; carry on with the scan below exactly as before. No error, no banner, and nothing attributed to a ledger that has nothing in it — a reflection with no ledger line to cite is still a valid reflection, and every session before 2026-08 has none. ## What to scan in this session 1. **Decisions made** — did you create an ADR? Did you make a decision that *should* have become an ADR but didn't? (the rule says "any non-obvious decision" — be honest.) 2. **Friction encountered** — did you have to explain the same convention to Claude twice? That's a `PROJECT-CONTEXT.md` candidate. 3. **Workarounds applied** — did you bypass a rule or use a one-off command? Why? Should the rule change, or should there be a new entry in PROJECT-CONTEXT.md's "Known stack gotchas"? 4. **Skills that didn't fire** — did Claude paste a prompt's content instead of loading a skill? The skill's `description:` may not match the trigger phrase the user actually used. 5. **Tools used that surprised you** — was an agent invoked when a direct Read would have been faster? Was main-thread context bloated by grep results? Subagent policy adjustment needed? 6. **Patterns that recurred** — did you tell Claude to do something three times that could be a hook? ## What to output A proposal — **not** a commit. The user decides what lands. ``` 🪞 Session reflection — What worked: - What hurt: - Proposed kit changes (review before applying): 1. [PROJECT-CONTEXT.md] Add to "Known stack gotchas": — . Reason: . 2. [SOP.md §] Tighten rule: → . Reason: . 3. [skills//SKILL.md] Update description to include trigger phrase: "". Reason: . 4. [hooks/hooks.json] New hook candidate: running . Reason: . ADR backlog (decisions made this session without an ADR — file these now): - made at . Should be ADR-. Tech debt observed (file as BACKLOG entries): - User confirmation needed to apply any of the above. ``` ## Output rules - **Propose, don't commit.** No file edits during reflect. The user reviews and explicitly approves each item before it lands. - One proposal per finding — not bundled. - Cite evidence: "I noticed X at " — concrete, not vague. - Skip the section entirely if there's no finding for that category. Don't pad. - ≤ 30 lines total. If the session yielded more than 5 findings, prioritise the top 3 and note the rest as "additional minor findings: ". ## Anti-patterns - Proposing rule changes for one-off situations. The bar is "this would have helped me twice or more in the past month." - Suggesting new skills when a richer description on an existing skill would solve it. - Auto-applying proposals without user approval — even small ones. The user owns the kit. ## Non-negotiable rules from CLAUDE.md - Read-only — reflect proposes; user applies. - Subagent delegation for multi-file scans of past sessions. - If a proposal touches `_00-Project-Management/90-Standards/SOP.md`, also bump the file's `version:` field in frontmatter once the user approves. ## End-of-reflect summary A single line: "X proposals · Y ADRs to backfill · Z tech-debt items. Apply now? (y/n)"