learn-lessons
Process lessons/ entries as doctrine change-requests.
SKILL.mdskills/learn-lessons/SKILL.md
GitHublearn-lessons — Lesson Processing and Queue Activation
learn-lessons runs the lessons family of queue-grind profiles over state/lessons/*.yaml (and
state/lessons-outbox/ in central mode) as change-requests against doctrine, agent prompts, hooks,
scripts, wiki guides, and improvement queues — one destination + change-kind per lesson. Success
metric: did doctrine and queues evolve, not did the file shrink. Supersedes
coordinator:lesson-triage. Taxonomy, change-kind apply dispatch, promotion-sprint procedure and
phase mechanics: wiki.
Every coordinator CLI named on this page is engine-homed and has a settings-home launcher —
resolve each by absolute path per ${CLAUDE_PLUGIN_ROOT}/snippets/resolve-coordinator-bin.md (Shape W on a PowerShell
host, Shape A/B on POSIX). Never a bareword, and never coordinator/bin/<cli>.py cwd-relative:
this skill runs with cwd set to the consuming repo, where that path does not exist.
Announce: "I'm using the coordinator:learn-lessons skill in <mode> mode." Mode default: cwd
~/.claude central → central; else local; PM can override.
Hard Rules (not engine-enforced)
- Actor split. The run's committer stage commits the run's fixes and closes. The EM commits
everything outside a run: post-run promotes and
promoted_tostamps, baton minting, PM-ruling writes, and the run stamp. A dispatched lead never commits. - No-defer. A
wiki-append/wiki-newrecord with a named destination applies THIS run. Legitimate deferrals: a structurally-required cross-mode block (e.g.strip-localbefore its central commit SHA lands), or a record needing PM authorization. - Wikis are the default destination.
doctrine-edit/memory-pointerare doctrine-plane-only — a worker NEVER emits either; downgrade towiki-*+doe_escalation: truebefore the record reaches the PM gate. - Extraction never runs through an LLM (
extract-lessons— a parse); routing judgment can, behind the verify gate. - Mechanical-contract lessons need an executable witness (test, live behavior, official docs) — discard if none or one contradicts the claim.
- Domain-looking universals default to
retag-local, never a blind[universal]string replace. - A
wiki-append/wiki-newtarget must be reachable from a real traversal surface (index, skill step, dispatch preamble) — not merely exist. - Local mode auto-applies
discard/wiki-append/retag-local/dedupe/age-sweep plus tradeoff-freeagent-prompt-edit,hook-edit,script-edit,snippet-sync-update,project-structuralrows below plan weight; the PM surface keepsdoctrine-edit,memory-pointer,doe_escalation, and product/taste choices. - Central mode needs a PM decision per record (apply / defer / reject, batching OK, per-cluster
allowed) — never auto-applied; the
lessons-central-routepm-decisionhand-back is the mechanism. - A strip run follows the apply run it cites — no row strips before its central commit exists.
- Fail-close: a strip-list id with no routed sibling record blocks the
COMPLETEsentinel — surface to the PM. - Universals-pending is a post-run count, not a pre-run stop: a local run hands back
route-to-central; surface ≥ 20 in the Phase 8 report with a central-run recommendation. - Never fabricate a routing
id, and never hand-correct a router's output — re-dispatch it. - An emit refusal is reported, not routed around.
Phase Flow (invocation pointers — mechanics: wiki)
coordinator_core.learn_lessons_pipeline's brief/apply entrypoints emit the Phase 4.5 cutoff
derivation and the Phase 8 COMPLETE stamp as engine directives — read them from the fired decision
object, never derive them by hand.
Discovery roots: learn-lessons-roots (machine-registry-derived). Baton lift source: batons joined
to the plan under distillation by deliverable_id, each ## What I Learned bullet a candidate
lesson, never an auto-promote.
One flow per run kind, each pre-run directives → emit → fire → consume hand-back → post-run directive:
- local: the
learn_lessons_pipelinebrief's age-sweep directive as the only pre-run step — never write routing records understate/lessons/; the grind writes them under<run_dir>/records/. Emit withemit-dispatch-workflow --queue state/lessons --profile lessons --appetite <a> --out <scratch>, fire with theWorkflow({scriptPath, args})call it prints, never--fire. - central route: drain the outbox, then assert cross-plane emptiness first (a FAIL stops the
run and goes to the PM). Emit
--queue state/lessons-outbox --profile lessons-central-route, fire, then present thepm_decisionhand-back to the PM; the EM writes each ruling aspm_decisionand commits.deferrows go tocoordinator-queue-append --schema improvement-queuewithqueue_scope: central;rejectrows close asdiscardedthroughbacklog-grind-assemble grind-row close. Cluster rulings: wiki § Phase flow detail. - central apply: emit
--profile lessons-central-apply, fire, then write the run stamp once every apply commit has landed and the fail-close holds. - strip: emit
--profile lessons-stripper repository after the apply run, with--where promoted_to in [...]copied from the apply run's settled list. A sibling launch needs the PM's cross-repo assent, asked once per strip session as one bundled ask; without it the strip waits.
Actor per flow. Whoever executes this skill (EM or dispatched lead) runs each flow's pre-run directive, emits, fires, and consumes the hand-back; commit authority stays EM-only.
Post-run consumption, all runs. baton → cluster and mint batons carrying triage's sizing
evidence, with no second gate (the fire authorized them); needs-judgment, doe-escalation and
direction-call → the PM; route-to-central → coordinator-lesson-promote per row with
--title-file/--body-file, then write promoted_to on the row and commit; engine-originated
types → counted in Phase 8, rows left open.
Cross-repo channel (local mode, run in a sibling). The sibling EM commits only its own row's
promoted_to stamp; the central-mode EM commits the outbox file(s) before the central route run
reads them. No dry-run mode; the Phase 8 report cites state/queue-grind/<profile>/runs/<run-id>.json.
Emit the Phase 8 end-of-run report (exempt from the ≤200-word budget — the run's only audit trail),
built from the engine's receipt and hand-back document, as that same actor's own run output, before
writing the COMPLETE sentinel. COMPLETE is blocked while a route-run row carries no pm_decision, or the apply run
handed back an engine-originated type — surface those to the PM first. The top-level EM writes the
sentinel last, after every apply/commit lands, never a dispatched lead, which cannot commit.
Wrap the emitted report in the marker pair, which is how the exemption is declared to the comms
hook (em-pm-comms-instrumentation.md § The ceremony-mandated marker):
<!-- ceremony-mandated:start -->
...the Phase 8 report...
<!-- ceremony-mandated:end -->
Anti-Patterns
Auto-applying central promotions without the PM gate; git add -A for strips; true-deleting a
discard instead of archiving first; default-routing to CLAUDE.md; defer-chaining wiki promotions
(every record is applied, PM-surfaced, or mode-escalated); a hand-rolled fallback when the emitter
is unavailable. Full list: wiki.
Related
wiki (full reference) · ${CLAUDE_PLUGIN_ROOT}/queue-profiles/lessons.yaml,
lessons-central-route.yaml, lessons-central-apply.yaml, lessons-strip.yaml ·
${CLAUDE_PLUGIN_ROOT}/snippets/em-operating-doctrine.md § How to Plan and Hand Off, "Improvement Queue"