Skip to content
Skills Library
AI & agents · Review & audit

reflect

/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).

Repository
tandem ↗
Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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).

Original author description

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).

How it works

  1. Ground the scan in the ledger first
  2. What to scan in this session
  3. What to output
  4. Output rules
  5. Anti-patterns
  6. Non-negotiable rules from CLAUDE.md
  7. End-of-reflect summary
Original SKILL.md headings · 87 lines, 720 words
SKILL.md preview
---
name: reflect
description: 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).
---

# 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 <YYYY-MM>
```

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 — <ISO date>

What worked:
  - <specific thing, ≤2 lines>

What hurt:
  - <specific thing, ≤2 lines>

Proposed kit changes (review before applying):
  1. [PROJECT-CONTEXT.md] Add to "Known stack gotchas": <symptom> — <fix>. Reason: <one line>.
  2. [SOP.md §<N>] Tighten rule: <current text> → <proposed text>. Reason: <one line>.
  3. [skills/<name>/SKILL.md] Update description to include trigger phrase: "<phrase user actually used>". Reason: <one line>.
  4. [hooks/hooks.json] New hook candidate: <event> running <command>. Reason: <one line>.

ADR backlog (decisions made this session without an ADR — file these now):
  - <decision> made at <timestamp/commit>. Should be ADR-<NNNN>.

Tech debt observed (file as BACKLOG entries):
  - <observation>

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 <approx point in session>" — 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: <count>".

## 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)"

Versions

RepositoryScoreLicence
This page · data-ai-xyz/tandem100MIT
iliaal/ai-skills100MIT
chhoumann/t3-pstack100MIT
chmonitor/chmonitor100GPL-3.0
backnotprop/pstack100MIT
guangshinhaha/shinstack100MIT
unsady/den100Apache-2.0
akdevsaha-dev/factory-skills100MIT
kriegcloud/beep-effect100Apache-2.0

Database snapshot: 13.11.2026 · package version 56919078f8f6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100session-recap
    Use when the user asks to recap, summarize, or review a Claude Code session — e.g. 'recap my last session', 'what happened in that session', 'session summary
  • 100claude-md-updater
    Scans the session for durable lessons and workflows, then proposes scoped project instruction updates. Use for save this lesson or add to context.
  • 100reflect-solution
    Summarize WHAT WAS SHIPPED in a Claude Code session as a self-contained HTML slide deck — the elevator pitch (problem, solution, decisions, artifacts, verification, gaps), not a play-by-play of tool calls or debugging detours. Defaults to the current in-context session;…
  • 100session-learning
    This skill should be used when the user asks about "session learning", "learn from session", "improve future sessions", "session reflection", "session metrics", "session analysis", "/session-reflect", "req learning", "learning updates", "rollback learning", or wants to…
  • 100session-reflect
    Reflect on a session and find what went wrong. Route each lesson to the strongest fix, from architecture or a type to a lint, a test, and last a written rule, and apply only what the user approves. Use when the user asks to reflect, for a retro or for lessons learned, or…
  • 100session-reflect
    Background reflection on conversation history. Extracts user preferences, corrections, and workflow patterns into USER.md. Triggered by heartbeat at the 4-hour quiet mark — never call directly.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.