---
name: session-review
description: >-
  Reflect on the current Claude Code or Codex session, identify legitimate learnings worth preserving (project gotchas, user preferences, mis-attributions, reusable workflows), classify each into the right destination (preferring the host-appropriate checked-in project instructions or a new skill over local-only auto-memory), present the proposals for user approval, and apply approved changes. Trigger when the user asks to "review this session", "振り返って", "capture learnings", "anything to add to CLAUDE.md?", "何か追加するものは?", "session retrospective", or any other phrasing that asks for post-session reflection on what should be captured.
---

# Session Review

Look back over the current conversation, surface the *legitimate* learnings that survive into future sessions, classify each into the destination where it belongs, ask the user which to apply, and write the files.

The single most important property of this skill is **honest filtering**. A bad retrospective floods rules files with one-off context and ephemeral plans; a good one keeps the corpus thin and high-signal. **Empty is a valid result** — if the session was routine, say so and add nothing.

## Claude Code / Codex runtime

Use the same filtering and approval workflow on both hosts. In Claude Code, `AskUserQuestion`, `Read`, `Edit`, and `Write` refer to the corresponding tools. In Codex, use the available question, file, and shell tools; if a question tool is unavailable, ask in chat and wait for an explicit answer. Do not apply a proposal before that answer.

Before classifying candidates, read the applicable project instructions and resolve imports such as `CLAUDE.md` containing `@AGENTS.md`. Follow the repository's existing ownership of shared instructions rather than duplicating rules.

| Host | Project facts and process rules | Reusable workflows | Personal memory |
|---|---|---|---|
| Claude Code | Existing `CLAUDE.md` / `.claude/rules/`; when `CLAUDE.md` imports `AGENTS.md`, edit the shared file for shared guidance | Existing `.claude/skills/<name>/SKILL.md` convention | Claude auto-memory, only for personal context with no checked-in home |
| Codex | Applicable `AGENTS.md`; long topic-specific guidance can live in a checked-in document explicitly referenced from `AGENTS.md` | `.agents/skills/<name>/SKILL.md` | Only use a memory capability actually provided by the host; otherwise propose a checked-in destination or skip the candidate |

The classification table and examples below describe Claude Code destinations. In Codex, substitute the destinations in this table throughout classification, proposal text, and application. Never save Codex-only guidance to `.claude/rules/` or `~/.claude/projects/`. Do not invent an automatic memory directory or modify user-global instructions without the user's approval. An explicit request to capture a learning in a particular file takes precedence.

## Workflow

### 1. Scan the session for candidates

Re-read the conversation with these lenses:

- **Surprises**: places where the user corrected you, redirected the approach, or accepted a non-obvious choice without pushback. Both directions matter — corrections AND validated judgment calls.
- **Mis-attributions / mistakes**: places where you cited the wrong source, asserted something the user proved false, or made a wrong assumption that wasted time.
- **Project gotchas**: non-obvious behaviors of the codebase, build tooling, framework, or runtime that surfaced during the work. Things a future contributor would benefit from knowing.
- **User preferences**: workflow choices, style preferences, terminology, decision patterns the user demonstrated.
- **Reusable workflows**: multi-step processes you executed that generalize beyond this one session.

For each candidate, draft a one-sentence summary in your head and ask: *Would future-me, dropped into a fresh conversation, change their behavior because of this?* If no, drop it.

### 2. Classify each surviving candidate

Match each candidate to exactly one destination.

**Prefer checked-in destinations by default.** Use the host-specific table above. In Claude Code, `CLAUDE.md` / `.claude/rules/` / a skill all live in the repo, so they sync via git to every machine and every contributor. Auto-memory lives under `~/.claude/projects/<encoded-path>/memory/` — it is **local to this one machine and never checked in**, so a learning saved there is invisible after a fresh `clone`, on a second machine, or to teammates. Reach for auto-memory only when a candidate has *no* home in the repo **and** is personal / non-shared cross-session context (e.g. `user` attributes, the volatile `project` progress state). When a candidate could plausibly go to either a checked-in file or auto-memory, the checked-in file wins.

| Destination | What belongs here |
|---|---|
| **`.claude/rules/<topic>.md`** (checked in — first choice for process) | Process conventions (project-specific or general): how to write tests in this repo, when to ask the user, comment style, git/PR rules, how work should be conducted. Each rule file is one topic. |
| **`CLAUDE.md`** (project root, checked in — first choice for codebase facts) | Non-obvious codebase facts: build/runtime quirks, framework version gotchas, file-layout invariants, generated files and what regenerates them, etc. Usually goes under existing sections like "Notes for editing". |
| **New skill / command** (checked in — first choice for reusable workflows) | A reusable, generalizable multi-step workflow that emerged. Rare — most sessions don't yield one. If yes, recommend invoking the `skill-creator` skill rather than hand-authoring a SKILL.md. |
| **Auto-memory** (`~/.claude/projects/<encoded-path>/memory/`) — **local-only, not synced; last resort** | Cross-session context with no repo home that is fine to keep personal: `user` (who they are), `project` (volatile current progress), `reference` (external systems). `feedback` about *how to work in this project* is really a process convention — prefer `.claude/rules/` and only fall back here if it's genuinely personal. Always update `MEMORY.md` index. |

If a candidate doesn't match cleanly to one destination, that's a signal it isn't well-formed enough — go back and either sharpen it or drop it.

#### Quick rules of thumb

- "Don't do X" without a *why* → not capturable yet; ask the user the reason before saving.
- "X exists in file Y" → the code itself is the source of truth; only capture if X is non-obvious from reading Y.
- Feedback about *how to conduct the work* (when to ask, how to fan out subagents, what process to follow) → this is a process convention; default it to `.claude/rules/`, not auto-memory. Auto-memory `feedback` is for the genuinely personal, non-shareable kind only.
- "User wants the work split into separate PRs" → either a one-off context detail or, if the pattern recurs and is process-shaped, a `.claude/rules/` entry rather than an auto-memory note.
- Anything already documented elsewhere (existing rule, existing memory, CLAUDE.md, code comment) → skip; don't duplicate.

### 3. Filter aggressively before presenting

After classification, re-examine the list and remove anything that fails *any* of these:

- The candidate would be visible to a careful reader of the existing code/docs.
- The destination already contains a substantively-equivalent entry.
- The candidate is a hypothesis about a future scenario with no current trigger ("if someone ever adds a dark mode…"). YAGNI applies to rules just as much as to code.
- The candidate restates the literal task that just completed — those belong in PR descriptions and commit messages, not memory.

If filtering leaves zero candidates, tell the user honestly: "Nothing this session generated is worth capturing." Don't pad.

### 4. Present for user approval

Two equally valid shapes:

**Shape A — granular (preferred when candidates are heterogeneous):** one `multiSelect: true` question where each option is one candidate ("`<destination>`: `<one-line summary>`"). User picks the subset to apply.

**Shape B — all-or-nothing:** one single-select question with options `すべて作成` / `選択して作成` / `作成しない`. If the user picks `選択して作成`, follow up with Shape A.

Either way, phrase each candidate so the user can decide without re-reading the session. Bad: "Save the feedback about the thing." Good: "Save to `.claude/rules/styling.md`: 'Tailwind v4 requires explicit `cursor-pointer` rule for buttons.'"

With ≥4 candidates, group them by destination. In Claude Code use multiple questions in one `AskUserQuestion` call (max 4 questions per call); in Codex respect the available question tool's limits or ask in chat.

### 5. Apply approved changes

For each approved candidate:

- **Project instructions (`AGENTS.md` or the Claude destinations above)**: use `Edit` to append to the right section, or `Write` for a new rule file. Follow the surrounding file's bullet and heading conventions and the repository's line-wrapping rule; if it has none, don't hard-wrap paragraphs.
- **Auto-memory**: write a new file in the project's memory directory using the frontmatter format from the system prompt (`name`, `description`, `metadata.type`). **Always append a one-line entry to `MEMORY.md`** — orphaned memory files are invisible.
- **New skill / command**: invoke `skill-creator` (or the `skill-creator:skill-creator` Skill). Don't try to hand-author a full SKILL.md from scratch — the creator knows the conventions, eval loop, and description-optimization steps.

### 6. Confirm

End with a brief summary: which destinations got updated, the file paths, and (if relevant) any related issues/PRs the user should consider so the loop closes cleanly.

## Anti-patterns to avoid

- **Padding the list to look thorough.** Three real captures beat ten ceremonial ones. The corpus is read every session and bloats fast.
- **Capturing the task description as a "project" memory.** "We fixed the cursor bug" is not a learning — it's already in the commit message.
- **Citing Claude Code default behavior as a project rule.** If you're about to say "per CLAUDE.md…", verify with `grep` first. Conflating sources (project-specific vs. default system-prompt guidance) erodes the user's ability to trust either.
- **Asking the user "is this a learning?" for every line.** Do the filtering yourself; only surface candidates that passed your own bar.
- **Skipping `MEMORY.md` index update** when writing a new memory file. Memory files are discovered only through the index; an orphaned file is invisible.
- **Hand-writing a new SKILL.md instead of invoking `skill-creator`.** The creator handles description optimization, eval setup, and packaging that you'll otherwise skip.

## Example interaction shape

```
User: 今回のセッション振り返って、何か追加するものある？

Claude Code example (in Codex substitute the destinations and tools above):
1. Scans session → finds 4 candidates
2. Filters → 2 survive (Tailwind v4 button gotcha → CLAUDE.md; rule-citation-accuracy → auto-memory)
3. AskUserQuestion (multiSelect) with both proposals
4. User selects both
5. Edit CLAUDE.md, Write memory file, Edit MEMORY.md
6. Summary: "CLAUDE.md updated (Notes for editing). Memory added: feedback_rule_citation_accuracy.md."

Other sessions, when nothing survives:
"This session was a routine bug fix — nothing crossed the bar for capture. Done."
```

## What this skill is NOT for

- Writing a session summary for the user to read. That's just plain-text recap.
- Drafting PR descriptions or commit messages. The PR/commit captures what happened in the code; this skill captures what should outlive the session in rules/memory.
- Logging every preference the user has ever expressed. Auto-memory has its own bar (described in the system prompt); follow that bar.