Reflect — promote staged learnings safely

You are folding the project's recent experience into its durable memory. This is the review gate that keeps auto-capture honest: nothing becomes a rule without your judgment, and every change is reversible.

Inputs

• .claude/knowledge/pending.md — candidates staged by the SessionEnd hook (each a ### entry tagged HIGH/MED).
• The current conversation (additional corrections the hook may have missed).

Procedure

1. Read pending.md and skim the recent conversation. Build a list of candidate learnings.
2. Judge each candidate against three tests — keep only if it passes all:
   • Specific — names a concrete behavior, file, command, or convention (not "write good code").
   • Reusable — will matter again in future sessions, not a one-off for this task.
   • Actionable — you can phrase it as a directive the next session can follow. Default to rejecting when unsure — a wrong rule is worse than a missing one.
3. Deduplicate: if a candidate restates something already in core-rules.md / conventions.md, skip it (or tighten the existing entry instead of adding a new one).

4. Route each surviving learning to exactly one home:

   • Behavior directive / "always|never" → .claude/rules/core-rules.md → Learned rules.
   • Project naming/pattern/anti-pattern → .claude/knowledge/conventions.md.
   • A gotcha + its fix → .claude/knowledge/bugs-and-fixes.md (one table row).
   • A repeatable multi-step procedure → suggest /distill <name> to make it a skill.
   • A durable architecture fact/decision → .claude/knowledge/architecture.md.

   When you add a bullet under Learned rules in core-rules.md, append a provenance tag so the loop is measurable later: - <rule> <!-- YYYY-MM-DD s:<session-id-prefix> -->.

5. Edit bounded & small (the SkillOpt principle): make the minimal edit that captures the learning. Keep each rule one or two lines. Don't bloat files — prune stale/contradicted rules in the same pass.
6. Back up & record:
   • Before editing a file, copy it to <file>.bak (gitignored).
   • Append a one-line entry to .claude/knowledge/session-log.md (- YYYY-MM-DD · <what was learned/changed>).
   • Move processed ### entries out of pending.md into .claude/knowledge/.archive/pending-<date>.md (create the dir; it's gitignored).
   • If the repo is a git repo, stage the changed knowledge/rules/skills files and commit: docs(knowledge): reflect — <short summary>. If not a git repo, skip the commit silently.
7. Mirror to AGENTS.md: if you promoted anything into Learned rules, run mise run mirror-rules (or python scripts/mirror_rules.py). It regenerates the <!-- BEGIN learned (generated) --> block in AGENTS.md from core-rules.md so Cursor / Copilot / Codex see the same rules. Include AGENTS.md in the commit from step 6.
8. Report a short summary: what you promoted, where, and what you rejected (and why).

Safety rails

• Never promote a candidate that contradicts an existing rule without flagging the conflict to the user and asking which wins.
• Never edit .claude/settings.json, hooks, or permissions from this skill.
• Keep core-rules.md tight (aim < ~40 rules). If it grows past that, consolidate.
• If pending.md is empty and the conversation had no corrections, say so and stop.