record-lesson

Bucket: workflow · Invocation: manual · /record-lesson (direct Claude), /agent-os:record-lesson (Claude plugin), or $record-lesson (Codex)

Captures a lesson while its evidence is fresh, at the narrowest level where it holds.

Repo level (the default): conventions, gotchas, verify commands, and delivery defaults that hold only in this repository go to the project policy section that init-agent-os seeds.

Global level: lessons about how the developer works that would hold in a repository that has never seen them go to policy.md in the agent-os repository — the source of truth behind the managed blocks. After that edit, the developer is reminded to run init-agent-os global to reinstall the blocks. An installed managed block is never edited directly; if the agent-os repository is not reachable, the workflow stops with the exact lesson text as a handoff.

The lesson lands as the smallest rule the next agent can act on, with the observed failure or insight that motivates it. The target is searched for an existing line with the same meaning: updated rather than duplicated, deleted when the lesson proves it wrong, and the resulting diff is always shown.

A machine-checkable lesson belongs in a test, script, or validator per the writing-skills enforcement ladder; it is routed there with at most a pointer left in policy prose. notice-lesson surfaces candidate lessons automatically when the developer interrupts or corrects the agent.