Reflect

Extract durable behavioral patterns from the current conversation and promote them — with explicit confirmation — into the harness memory tiers (memory/MEMORY.md, context/IDENTITY.md). Always appends a log entry regardless of outcome.

This is the deliberate "Improve" pass of the Memory Improvement Protocol defined in context/rules/memory.md. Running it as a named skill turns an optional afterthought into a first-class, propose-then-confirm operation.

When to use

• /reflect invoked explicitly to close a session.
• Proactively, after a session that produced decisions, surprises, regressions, or failure modes the next agent would benefit from knowing.

When NOT to use

• `/harness-audit` — audits harness code health via four parallel sub-agents. That is a structural audit, not a behavioral/conversational pass.
• `/context-audit` — scores the default-loaded context budget across four dimensions. It trims files, not behaviors.
• `/skill-lint` — scores individual skills for staleness. It reviews skill quality, not session outcomes.
• Trivial sessions — if the session contained only mechanical read-only queries or single-command invocations with no surprises, announce the skip and proceed to log.

/reflect is the only skill whose domain is current-session behavioral patterns → memory/identity.

Scope

Current conversation only. /reflect does not read prior daily logs, prior sessions, or the ~/.claude/projects/... auto-memory store. It works from what is already in context.

Instructions

1. Gather session signals

Scan the current conversation for:

• Decisions made and the reasoning behind them.
• Surprises — things that failed that seemed straightforward, or worked unexpectedly.
• Couplings, constraints, or edge cases that were non-obvious.
• Corrections the user made to the agent's behavior.
• Patterns in what the user asked for repeatedly.

Do not invent signals not present in the conversation.

2. Extract candidate patterns

From the signals, draft a list of candidate lessons — one per observation. Write each in one sentence, descriptive tone ("this session showed X"), not prescriptive. Include the session date (UTC).

3. Apply the qualify filter

Discard any candidate that matches any row in the "What Does NOT Go in Memory" table (context/rules/memory.md):

Also discard any candidate that is already captured, verbatim or in substance, in memory/MEMORY.md or context/IDENTITY.md. Link or skip; never double-write.

4. Classify surviving lessons by tier

For each surviving candidate, classify:

When in doubt between MEMORY.md and IDENTITY.md: if you would scope it to "this session" or "this codebase right now," it belongs in MEMORY.md. If you would remove the scoping and say "always," it belongs in IDENTITY.md.

5. Propose-then-confirm gate

Before writing to memory/MEMORY.md or context/IDENTITY.md, present the proposed additions as a clearly formatted block:

Proposed MEMORY.md addition(s):
- YYYY-MM-DD: <one-sentence lesson>

Proposed IDENTITY.md addition(s):
- <prescriptive principle, "always X" or "never Y">

Type APPROVE to write, SKIP to discard any item, or EDIT <n> <new text> to revise.

Do not write to either file until the user responds. Log-tier entries do not require approval.

If --dry-run was passed, skip writing entirely and report what would have been written.

6. Write approved changes

For each APPROVED item:

`memory/MEMORY.md` — append under ## Lessons Learned:

- **YYYY-MM-DD**: <lesson>

`context/IDENTITY.md` — append under ## Lessons learned (append-only):

- **YYYY-MM-DD**: <principle>

Both files are append-only. Never edit existing entries.

7. Append the log entry

Always run this step, regardless of whether anything was promoted. Get the current UTC time first:

date -u +%H:%M
TODAY=$(date -u +%Y-%m-%d)
mkdir -p "memory/$TODAY"

Then append to memory/<UTC-date>/log.md:

## Reflect -- HH:MM UTC
- **Result**: OP | DRY-RUN | SKIPPED-TRIVIAL
- **Candidates**: <count extracted before qualify filter>
- **Promoted**: <count written to MEMORY.md> to MEMORY.md, <count> to IDENTITY.md
- **Observation**: <one sentence on what the session's most significant pattern was, or "no durable patterns found">

MEMORY.md vs IDENTITY.md boundary

A lesson graduates from MEMORY.md to IDENTITY.md when it has recurred across multiple sessions or contexts, not from a single run. Do not graduate prematurely.

Auto-trigger note

Claude Code skills cannot self-trigger. True automatic firing at session end would require a Stop hook configured in settings.json via /update-config. That is explicitly deferred from v1 of this skill.

Anti-patterns

• Proposing without filtering. Running the qualify filter is not optional — a candidate list that hasn't been filtered is not ready to propose.
• Writing without confirmation. MEMORY.md and IDENTITY.md entries require explicit approval. The log entry does not.
• Double-writing. If a lesson already exists in MEMORY.md or IDENTITY.md, link or skip. Never add a duplicate.
• Graduating prematurely. One session is evidence, not a principle. IDENTITY.md entries need cross-session generalization.
• Reading outside current context. Do not read prior log.md files or external transcripts. Scope is the open conversation only.
• Skipping the log. Every invocation — op, dry-run, trivial skip — appends a log entry. No exceptions.