| name | retrospective |
| description | Turn the work just done into VETTED lessons that survive across sessions and projects — harvest the session's decisions/errors, draft candidate lessons, refute them adversarially, and promote only the survivors into taskmanager memories. The self-improvement loop, gated so a false lesson can never silently change how the suite works. Trigger: end of a substantial piece of work / a wrap-up moment, or when asked to capture lessons learned.
|
Retrospective — vetted lessons, never a false one
The suite gets better by learning from its own work — but a "lesson" is a claim, and an unrefuted
claim that silently changes behavior is how tools degrade. So this loop refutes before it promotes,
and it reuses what already exists: it writes nothing new — lessons live in taskmanager's memories
(which already has a draft status, confidence, supersession, and conflict tracking), and the
membrane is the existing adversarial-verify.
The loop (harvest → draft → refute → promote)
-
HARVEST (read-only). Gather what happened from docs/.scribe/capture.log (decisions/errors),
.maestro/ledger.log (verification passes + waivers — what was run, what survived, and what was
deliberately skipped and why), docs/incidents/ (postmortems), and the live session. Degrade
gracefully: if any of these paths are absent, harvest from what exists and still run — none is a
hard dependency.
-
DRAFT. Write each candidate lesson as a memories row with status='draft',
source_type='agent', and low confidence (well under the 0.8 default, so it reads as
unproven), kind = an existing enum value (process when unsure; anti-pattern/integration/
convention/architecture when one clearly fits). A draft is invisible to execution — every
memory loader filters WHERE status='active' — so an unpromoted lesson cannot affect work. (No
numeric promotion ladder, no scoring engine — draft vs active is the whole gate.)
-
REFUTE. Invoke maestro:adversarial-verify once for the batch — hand it ALL drafts as N
claims (not one spawn per lesson). Refute-first, default-wrong; escalate to multiple lenses only
for a lesson that would change a plugin's behavior (per the standard — multi-vote when it matters,
not ritual). A lesson "survives" only on conclusive evidence it's real and generalizable.
-
PROMOTE the survivors. Flip draft → active and raise confidence to the active default.
Overturned drafts stay draft (or deprecated) with the refutation recorded in
conflict_resolutions — so a refuted lesson is remembered as refuted, not silently dropped.
The binding ownership gate
- A net-new active lesson (supersedes nothing) is a create — agents may auto-promote it.
- A lesson that would supersede an existing active memory must ask the user (
AskUserQuestion)
before flipping the old one to superseded — never auto-override a standing decision.
- A memory with
source_type='user' / auto_updatable=0 is NEVER auto-updated or auto-superseded,
full stop. The retrospective must honor this or it can silently overwrite a human's call.
"Improve the plugins" is advisory, never an auto-edit
When a lesson implies the tooling itself should change (a skill/hook/gate), the retrospective
flags it for a human (an open-questions.md entry or a high-importance memory) — it does not
edit any plugin file. Auto-mutating the suite from a lesson is the exact path by which a false lesson
degrades the tools; that door stays closed.
What this does NOT build
- No new lessons store/file/table (memories already exist); no
lesson-verifier agent (reuse
adversarial-verify); no scheduled/continuous mining (triggered on wrap-up only); no scoring/ML
engine; no new hook (the existing session_retro.sh is the trigger); no auto-edits to any
SKILL.md/hook; no promotion of an unrefuted lesson to active.
