Lesson Learned

Turn what a session taught into the smallest durable change in the right owner, so projects align bit by bit without piling up rules. Run it on /lesson-learned or "lessons learned", and propose it as a (Lesson Learned) suggestion after an implementation, approved decisions, a correction, or a repeated instruction. skillify owns creating and extending skills, trim owns shortening, and AGENTS.md guidance defines what each instruction layer holds.

Workflow

1. Collect candidates: list the user's corrections, approved decisions with their reason, repeated instructions, workarounds, and rules that proved stale, wrong, or ignored, each with where it came from. Drop session-specific paths, one-off values, and secrets. Done when every correction and approved decision is listed or excluded with a reason.
2. Admit few: keep a lesson only when the situation will recur, an agent would likely get it wrong next time, and no existing rule already says it; search the owners first (rg -i '<keyword>' AGENTS.md ~/.agents/AGENTS.md ~/.agents/skills/*/ .agents/skills/). An ignored rule is a wording or placement problem, not a missing rule. Done when each candidate is admitted or rejected with one reason.

3. Pick one owner, strongest first:

   1. a test, check, lint rule, script, or code default that enforces it;
   2. the skill that owns the topic, through skillify when the change is more than a line or needs a new skill;
   3. the project AGENTS.md for a repository invariant;
   4. the global persona (dot_agents/AGENTS.md in fmind/dot) for a durable personal preference across projects;
   5. the project decision log, the brain through bf when the project has one, for a dated choice and its reason, including "do not re-raise" outcomes.

   Done when each lesson has exactly one owner and no copy elsewhere.

4. Improve before adding: don't just append. First sharpen, merge, or align the existing content the lesson touches, and delete what it makes stale; add a new line only when nothing existing can carry it. Done when each edit reports the words added and removed per file and instruction budgets still pass (dot agent context --project ., plus --source . in fmind/dot).
5. Propose, then apply: list each lesson as a (Lesson Learned) suggestion naming the owner path and the exact old and new text, ranked by impact. Apply only what the user approves, since approving a decision does not approve rule wording; then run the owner's checks (focused tests, mise run check:skills for skills, the formatter for docs). Done when approved edits pass their checks or the failure is reported.

Gotchas

• Prefer enforcement over prose: a check fails on every host and costs no context; a sentence is loaded every session and can still be ignored.
• Report "no lesson" plainly: most sessions change nothing durable; say so in one line instead of inventing a rule.
• Keep host memory out of the loop: harness memory (such as Claude Code's memory/ directory) is read by one host only, so route durable lessons to shared owners and migrate memory entries that hold them; touch memory only on the user's request, and never delete a memory file that a decision log cites as evidence.
• Keep agy /learn lessons in the dot source: its global scope writes ~/.gemini/GEMINI.md, which links to ~/.agents/AGENTS.md, so a global /learn write changes the shared persona for every harness until the next chezmoi apply --force overwrites it; it also writes rule files under ~/.gemini/config/rules/, or new skills under ~/.gemini/config/skills/ (~/.agents/skills), all outside the dot source. Approve its learning_proposal.md only for project scope; apply global lessons to the dot source with this workflow.

Documentation

• Companion skills: skillify (skill authoring), trim (shortening owners), repository-docs (instruction layers and Markdown style), bf (brain decision logs).