reflect

End-of-work reflection. Ask once: did anything learned here deserve to outlive this session? If yes, propose the smallest change that captures it. If no, say nothing and move on.

This skill is the self-updating-instructions mechanism. It is the alternative to a growing memory.md junk drawer. New knowledge should land in the place that already handles its kind — not in a new file.

When to use

Invoke at natural end-points of work, not after every turn:

• End of a process-inbox, reconcile, consolidate, or crystallize run.
• End of a substantive Query that produced reusable synthesis.
• Right after the user corrects an approach (“no, don’t do X”) or confirms a non-obvious choice (“yes, that was the right call”).
• When the user explicitly says “reflect” or “did we learn anything”.

Do not invoke:

• After trivial edits, lookups, or one-turn tasks.
• More than once per session. If a proposal was already made and accepted/declined, stop.
• When the session’s work is already fully captured by existing skills, log.md, or questions.md.

Default: stay silent

The bar is high. A reflection is worth surfacing only if all of these hold:

1. Durable — will still be true next week.
2. Non-obvious — not derivable by reading AGENTS, a skill, or the current file structure.
3. Not already captured — grep the likely destination first.
4. Generalizable — applies beyond the specific task that produced it.

If any fails, skip. Silence is the correct output most of the time.

Routing matrix

Match the learning to exactly one destination. Pick the most specific fit.

Kind of learning	Destination	Mechanism
User preference / cross-project fact about the human	~/.claude/.../memory/ auto-memory	Save a memory file per the auto-memory schema
Vault contract (routing rule, multilang convention, frontmatter, folder semantics)	AGENTS	Edit the relevant section
How to perform an operation (procedure, decision logic, edge cases)	Existing skill at 7_Agent/skills/<name>/SKILL.md	Edit that skill
An operation that doesn’t fit any existing skill	New skill	Invoke add-skill
A question the vault couldn’t answer	questions	Invoke log-question
A page earning durable-citation status	2_Areas/_Canon/	Invoke crystallize
Transient operational event (what was done this session)	log	Already handled by the op skill — don’t duplicate

If two destinations seem to fit, prefer the more specific (skill edit over AGENTS edit; AGENTS edit over auto-memory).

Procedure

1. Scan the session silently. What did the agent do, and what feedback/corrections/validations did the user give? What was non-obvious?

2. Filter against the four bars (durable, non-obvious, not-captured, generalizable). Drop everything that fails.

3. Pick at most one surviving learning. If multiple survive, choose the one with the highest future-payoff. The others can wait — reflection runs again later.

4. Grep the destination to confirm it isn’t already there. If it is, stop.

5. Draft the minimal change — one rule, one frontmatter field, one routing-table row. Not a rewrite.

6. Propose, don’t apply. Surface one concise question to the user with the diff inline:

   I noticed . Worth adding to as ? (yes / no / later)

   Use the agent’s ask-user mechanism where available (e.g. AskUserQuestion in Claude Code). If no interactive channel exists, state the proposal plainly and wait for the next turn.

7. On “yes”: apply via the destination’s own skill (add-skill, log-question, crystallize, or a direct edit). Append a one-line entry to log: reflect: added <thing> to <destination>.

8. On “no” or “later”: drop it. Do not persist the proposal anywhere. Don’t ask again this session.

Anti-aggression rules

• One proposal per session, max. If you made one already, stop.
• No laundry lists. Multiple bullet points of “things you could learn” is noise. Pick one.
• No speculative learnings. Only propose things grounded in actual session events — not things the agent imagines might be useful.
• No rewrites dressed as reflections. If the proposed change is larger than a few lines, it’s a refactor, not a reflection — ask the user explicitly whether to do that work, don’t smuggle it in.
• Respect prior declines. If the user said “no” to a similar proposal recently (visible in log.md or conversation), don’t re-propose the same thing.

Output

Exactly one of:

• Silence. (Most common. Correct default.)
• A single proposal with destination, proposed change, and a yes/no/later prompt.

No summaries. No “here’s what we learned today” recaps.

Anti-patterns

• Creating memory.md or any dumping ground. The whole point of this skill is that such a file doesn’t need to exist.
• Proposing things that are already in AGENTS or a skill. Grep first.
• Logging the reflection itself as content. log.md gets one line after a change is applied — not a record of reflections that were declined.
• Running inside add-skill, crystallize, log-question, etc. Those are the destinations. Don’t recurse.
• Asking “did we learn anything?” unprompted at the end of every turn. That’s the aggressive pattern the user explicitly said no to.