Manage Lessons Skill

Manage lessons learned with global scope. Stores lessons as markdown files with key=value metadata headers. A lesson's lifecycle state ("unapplied" vs "applied") is encoded by its on-disk location, not by metadata: unapplied lessons live in .plan/local/lessons-learned/{id}.md, and become applied by being moved into a plan directory as .plan/local/plans/{plan_id}/lesson-{id}.md via convert-to-plan.

Enforcement

Base contract: See manage-contract.md for shared enforcement rules, TOON output format, and error response patterns.

Skill-specific constraints:

• Only valid category values: bug, improvement, anti-pattern, arch-constraint
• arch-constraint lessons require --rule on add (the dedup key) and follow a rule-identity dedup + retire-on-quiet lifecycle (see Categories and standards/file-format.md)
• Lessons are global-scoped (not plan-specific); no --plan-id parameter
• The from-error command expects JSON context as --context argument

Canonical flag names (do not invent aliases):

• The lesson-selector flag is --lesson-id on every verb that targets a single lesson (get, update, set-body, set-title, convert-to-plan, remove, supersede, and the explicit-ids mode of cleanup-superseded). There is no --id flag — the bare id token appears only as an output field and as a metadata header key (see Metadata Fields), never as an input argument. Passing --id is rejected by argparse (exit_code: 2).
• Lifecycle filtering on list is done with --status {active|superseded|removed|all} (default active; use all to include superseded/removed lessons). There is no --include-tombstoned flag — --status all is the canonical way to surface non-active lessons. Tombstones at .tombstones/{id}.json are the audit trail for supersede/remove events and are not listed by any verb; they are never exposed through a list flag.

Storage Location