oduffy-delphi/learn-lessons

learn-lessons — Lesson Processing and Queue Activation

learn-lessons processes per-entry state/lessons/*.yaml files as change-requests against doctrine, agent prompts, hooks, scripts, wiki guides, and improvement queues — one destination + change-kind per lesson, tracking recurrence and archiving discards. Success metric: did doctrine and queues evolve, not did the file shrink. Supersedes coordinator:lesson-triage (renamed; no alias shim). Modes, the routing schema, the fabrication-verify-gate mechanics + recovery playbook, the Phase 8 report shape, and the heavy-queue promotion-sprint procedure: wiki.

Every coordinator CLI named on this page is engine-homed and has a settings-home launcher — resolve each by absolute path per 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)

• No-defer. A wiki-append/wiki-new record with a named destination applies THIS run — never "the next pass." Legitimate deferrals: a structurally-required cross-mode block (e.g. strip-local before its central commit SHA lands), or a record needing PM authorization.
• Wikis are the default destination. doctrine-edit/memory-pointer are doctrine-plane-only — a worker NEVER emits either; downgrade to wiki-* + doe_escalation: true before the record reaches the PM gate.
• Extraction never runs through an LLM (extract-lessons — a parse, not a judgment call; an LLM extraction pass produced a real fabrication incident). Routing judgment can, behind the verify gate.
• Mechanical-contract lessons need an executable witness (a passing test, live tool behavior, official docs) — discard if none can be found or one contradicts the claim; narrative confidence alone never overrides a converging set of independent authorities.
• Domain-looking universals default to retag-local, never a blind [universal] string replace (corrupts retag history).
• A wiki-append/wiki-new target must be reachable from a real traversal surface (index, skill step, dispatch preamble) — not merely exist.
• Central mode needs a PM decision per record (apply / defer / reject, batching OK) — never auto-applied. Local mode auto-applies discard/wiki-append/retag-local/dedupe/age-sweep; PM-surfaces doctrine-edit, memory-pointer, doe_escalation, agent-prompt-edit, hook-edit, script-edit, snippet-sync-update, project-structural. strip-local is NOT PM-surface.
• Central strips only after its own promotion's commit SHA exists, same run — never deferred to the sibling's next age-sweep.
• Fail-close: an undated-universal leak, or a strip-list id with no routed sibling record, blocks the run's COMPLETE sentinel — surface to the PM, don't push through.
• Universals-pending: if ≥ 20 unactioned [universal] entries, surface to PM before proceeding.
• Never fabricate a routing id — every cited id must exist in its extraction, or the mechanical verify-gate hard-fails the apply. Never hand-correct a router's fabricated output; re-dispatch it instead (launders the fabrication into the audit trail otherwise).

Phase Flow (invocation pointers — mechanics: wiki)

Discovery roots: learn-lessons-roots (machine-registry-derived, never a committed list). Baton lift source: batons joined to the plan under distillation by deliverable_id; each baton's ## What I Learned section is a flat bullet list, one standalone lesson per line, no sub-headings and no nesting — that shape is fixed so a line survives being lifted out of the baton with nothing around it. Every line read this way is a candidate lesson, never an auto-promote: the EM still decides to promote, amend, or drop it through the same routing/gate mechanics as any other extracted lesson. Extraction: extract-lessons.py extract. Routing populates candidate_restatements via coordinator_core.learn_lessons_assemble.generate_candidates(...) (or learn-lessons-reconcile-candidates for bulk). Central mode also runs an undated-pass via coordinator_core.ops.lessons_filter.filter_undated_universal(extraction_yaml) (registered op lessons.filter_undated_universal) and drains state/lessons-outbox/ via lessons-outbox-drain.py (read → assert cross-plane emptiness → group → dedupe → apply → mark drained). Verify: extract-lessons.py verify <extraction> <records.yaml>. Strip-orphan check: learn-lessons-age-sweep check-strip-orphans <records.yaml> <strip-list.yaml>. Local-mode age-sweep bounds state/lessons/: learn-lessons-age-sweep cutoff then age-sweep-lessons.py --before <cutoff> [--apply]. Universal-routing queue fork: coordinator-lesson-promote (central-wiki target) / auto-apply (project-local wiki) / coordinator-queue-append --schema improvement-queue (project scope). Recheck-mode delta: query-records --type lesson --since <date>, cadence marker at state/lesson-triage-recheck-due- <date>.md, volume nudge via central-run-due.

Emit the Phase 8 end-of-run report (exempt from the ≤200-word budget — the run's only audit trail; do not convert to report-by-exception) before writing the COMPLETE sentinel; the sentinel is written last, after every apply/commit lands.

Anti-Patterns

Auto-applying central promotions without the PM gate. Bespoke extra parameters (modes are the parameter surface). git add -A for strips. True-deleting a discard instead of archiving first. Conflating the improvement queue with state/lessons/ (capture queue vs. this periodic router). Same-session capture-and-validate a lesson as universal. Default-routing to CLAUDE.md instead of a wiki. Defer-chaining wiki promotions as "candidates for next pass" — every record is (a) applied, (b) PM-surfaced, or (c) mode-escalated, no fourth bucket. Declaring "no additional work needed" while project-specific (non-[universal]) entries remain un-routed. Full list + rationale: wiki.

Related

wiki (full reference) · ${CLAUDE_PLUGIN_ROOT}/snippets/em-operating-doctrine.md § How to Plan and Hand Off, "Improvement Queue"