retrospective-distill
Turn completed session records into verified follow-up candidates.
SKILL.mdplugins/vouchington-workflow/skills/retrospective-distill/SKILL.md
GitHubRetrospective distillation
Read applicable AGENTS.md and their declared adapter alias, otherwise
.agents/skills/retrospective-distill/SKILL.md from the repository root if present.
Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
Use when completed retrospectives or journals should become durable follow-up work. Read local
AGENTS.md, issue policy, and journal retention rules before any mutation.
- Enumerate only completed, eligible session records with the
snapshot_exporttool of thevouchington-toolingMCP server, narrowing byagent,version,parentSessionId, exactdatafields, anddataArrayContains. It exports non-archived sessions to a private local file and returns the path, counts, checksum, and manifest, never the records. Before exporting, calloutbox_flushand thenoutbox_statusfor every worktree thatgit worktree listreports, passing each path asworktree, and stop if any reports aworktreePendingCountabove 0. Use the worktree count, neverpendingCountorstatus, which cover only the caller's own session: the sessions to distill belong to other agents, and an archived session refuses later delivery, so a retained record would never be distilled. Outboxes in removed worktrees or on other machines cannot be drained this way, so apply the age cutoffs under session shapes to give them time to deliver. Leave in-progress sessions intact. If a search forsnapshot_export(the tool names carry a harness prefix, see the blackboard skill) finds no server, stop and report it; do not fall back to a CLI command. - Before using any record, verify the file against the returned checksum, counts, and terminal
manifest with the consumer's approved snapshot reader, and stop on a mismatch rather than
treating missing records as absent. Require
manifest.schemaVersionto be 1,manifest.statusto be"complete", a nonemptycleanupToken, and manifest counts that exactly match the export counts, including the terminal manifest record. Hand subagents only read-only partitions of the verified file, never the original snapshot. Bound each partition to at most 25 contiguous session groups or 1 MiB. A session's record and entries form an indivisible group, so fail the run rather than split a group or weaken the bound. Only the root keeps thecleanupToken; never delegate it. Read full records, with their storage type, repository tags, source identity, coverage, and outcomes, from that file. Do not distill fromjournal_entries: it reads one session at a time and has no checksum or manifest to show that the read is complete. For repository-scoped work, filter sessions by repository membership (dataArrayContainswithrepositoriesand the exactowner/name) and use only entries attributed to that repository. Leave untagged legacy records unclassified. Do not infer their repository. - Validate storage type and the shared envelope independently of optional category. Never repair
unknown legacy types or repository provenance by inference. Quarantine malformed sessions with
an explicit reason while processing valid unrelated sessions. Deduplicate at-least-once records
by exact session/source identity and reject conflicting duplicate content. Records that differ
only in their server-assigned
timestampare one event. Retain coverage, dropped counts, requested versus observed outcomes, and useful resolved findings. Classify each session by shape and skip any that is not yet eligible, with a reason. - Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues. Treat a finding already linked to an open tracker as context, not a duplicate.
- Verify each candidate against the current base. Search existing issues and open changes before
drafting. Skip work that is complete, explicitly rejected, or already covered. A first-party version
bump is not proof of resolution: verify the adopted change against the original finding before
deferring. Capture a new observation in the journal before filing it.
Inspect against the refreshed remote default branch, never the local one, which may sit on an
unmerged branch. Before filing a claim such as "direct-to-main" or "merged without CI", verify it
with
git branch -r --contains <sha>andgit merge-base --is-ancestor <sha> origin/<default>. Prefer a retrospective's generated verifiable facts over its narration, and verify journal-only claims the same way before they reach an issue body; an agent's in-session narration is not evidence. - Draft self-contained issues with the problem, concrete proposed work, relevant areas, and validation, using the issue body template. Route every authorized creation through github-issue, including its repository gate, label approval, and denied-external tracking behavior.
- Archive only verified records fully processed across every represented repository, and never
while any worktree's
outbox_statusreports aworktreePendingCountabove 0, under the repository's retention rules. Make onesession_archivecall per session, whosesessionIdis the archived session, not the caller. Immediately before each call, read that session withjournal_entriesand archive only if its entries match the verified snapshot's by source identity; otherwise leave it for the next pass, because an entry added after the export would never be distilled. Archiving makes the session's metadata immutable, so it needs the archival authorization that local policy requires. A one-repository pass leaves a multi-repository session active until the other repositories are reviewed. Report reviewed, fixed, duplicate, deferred, quarantined, and actionable dispositions with reasons. Keep the top five themes in human prose without dropping underlying findings or unresolved records.
Session shapes and eligibility
Classify by each entry's type, never by rendered text. Deduplicate by session and sourceEventId
first. Entries that differ only in the server-assigned timestamp are one event; any other
difference is a conflicting payload and stays quarantined.
| Shape | Definition |
|---|---|
| Entry-type-unresolved | At least one entry has a missing type, a type other than journal or retrospective, or a feedback envelope that fails the shared validator, even if the session also has a retrospective. |
| Retrospective | Has a retrospective entry and no unresolved entry. |
| Checkpoint-only | Has entries, no retrospective, and every entry is a historic hook-written checkpoint, identified by a structural checkpoint field. |
| Journal-only | Has entries, no retrospective, and at least one entry is not a checkpoint. |
| Zero-entry child | No entries and a non-null parentSessionId. |
| Zero-entry root | No entries and a null parentSessionId. |
- The zero-entry split names session topology, not completion. A delegated child that died mid-task looks identical to one that finished cleanly; never read it as "completed normally".
- Report entry-type-unresolved sessions separately. Give them no issue-filing pass or archival this run, whatever their age; do not treat an untyped entry as journal evidence.
- Compute
retroAtas the newest retrospective entry'screatedAt, andlastActiveas the newest normalized entry'screatedAt, falling back to the session'screatedAtwhen it has no entries. An identical replay does not advance activity; a new source event does. - Compute
retroCutoff = now - retroDaysandsessionCutoff = now - sessionDaysonce, from caller-supplied non-negative finite day counts, and share both with every inspector so none reads its own clock. Reject a negative or non-numeric count before exporting: it makes the cutoff lie in the future or every comparison false, and these values gate archival. - Every shape except entry-type-unresolved is eligible when
(has a retrospective AND retroAt < retroCutoff) OR (lastActive < sessionCutoff). Session age alone makes a stale checkpoint-only, journal-only, or zero-entry session eligible, so a retrospective-only gate cannot strand it. Everything else is not yet eligible; skip it with a reason. - Export unfiltered; the retrospective and session cutoffs above decide eligibility, and too-new sessions must still appear as skipped with a reason. Derive age from the cutoffs above; they supply the delay for outboxes in removed worktrees or on other machines.
- Journal-only and zero-entry evidence get full issue-filing rights, subject to the same duplicate, current-state, and dependency checks as retrospective evidence, plus redaction: never quote a journal entry's raw command string or stderr in an issue body, since a journal entry can carry unredacted secrets.
- Skip archival for sessions that contributed to a theme whose issue mutation failed this run, and for sessions whose only themes were deferred, since deferral promises re-evaluation. Keep a theme tied to a closed-without-merge issue or change eligible; do not treat open state alone as conclusive. Preserve each theme's contributing session IDs through merging and deduplication.
- Delegate partitions only to read-only inspectors, which must not call MCP, create issues, archive sessions, edit files, or keep a copy of a partition. Have each return a compact disposition summary: partition index, deduplicated themes with their session IDs, and each session's disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape is determined structurally.
- Keep the verified snapshot until the last
session_archive, because the archival check reads it. Then remove the snapshot with the cleanup capability returned at export, and any partitions with the separate receipt returned when they were created (the export capability cannot remove them), in a cleanup path that runs even when no session is archived. - Report reviewed, fixed, duplicate, deferred, quarantined, actionable, created, updated, not-yet-eligible, entry-type-unresolved, and archived counts with reasons, splitting eligible sessions into retrospective and stale (checkpoint-only, journal-only, zero-entry child, and zero-entry root).
Cleanup, as a finally step: whether processing succeeded or failed, call snapshot_cleanup with
the cleanupToken from snapshot_export, with the same sessionId and worktree, once the
snapshot is no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
retry the same call.
Use source records only for local verification and leave them in the repository's approved journal or retention system. Public issue bodies contain only the minimum bounded facts or redacted summaries needed to establish the problem, proposed work, relevant areas, and validation. Never embed unredacted logs, command output, environment details, provider payloads, or transcript content. A snapshot file is a private local copy of source records: never commit or attach it, or copy its contents into an issue.
This skill supplies no issue repository, labels, milestones, projects, or approval model; it reads
sessions only from the snapshot file that snapshot_export writes, and archives them only with
session_archive. Consumer wrappers cannot weaken this export
boundary; they provide only those local details.