Session Retrospective

Session Retrospective

Distill past sessions for this project into evidenced, ack-gated improvements to the team's memory and shared docs. Efficiency-led: process waste first, durable facts second. You (scout) run this manually when asked.

Read-only analysis, assisted writes. The parser only reads transcripts. You propose every change and write nothing until the user acks.

When to use

• The user says "run a retrospective", "mine past sessions", "what slowed us

down", or "improve the team from recent work".

• Periodically, to fold lessons from recent sessions into .agents/.

Not for: onboarding a fresh repo (that's seeding-a-project), or refreshing config from code/PR changes (that's scout's normal update flow).

Procedure

1. Distill. Run the parser from the project root:

`` node {skill}/scripts/distill-sessions.mjs ``

It reads ~/.claude/projects// transcripts newer than the watermark (.agents/memory/scout/.last-retrospective), plus each session's subagents/, and prints a bounded markdown digest. Add --all to ignore the watermark, --exclude-session to skip the active session, or --out to save the digest. Exit code 3 = no transcripts found → use the Fallback below. The newest session is usually the one you're running in — pass --exclude-session so the retrospective doesn't analyze itself.

1. Read the digest (it fits in context — never read raw .jsonl).

1. Interpret — see references/signal-taxonomy.md. Separate:

• Efficiency findings — repeated corrections, retry loops, file churn,

tool errors, ignored conventions.

• Durable facts — gotchas, decisions, "X doesn't work, use Y".

Every finding MUST cite the session id it came from. Drop anything you cannot evidence from the digest.

1. Map findings to targets — see references/finding-to-target.md:

role-specific → that role's .agents/memory//; team-wide process → .agents/workflow.md / .agents/conventions.md; durable fact → a curated entry (via the memory skill). If .agents/ doesn't exist, the project isn't seeded — a retrospective refines an existing lens, it doesn't create one; run seeding-a-project first.

1. Propose, then wait. Present each proposed change as a diff plus a

one-line rationale with its session-id evidence. Stop and wait for the user's ack. Do not write yet.

1. On ack, write:

• Memory deltas via the memory skill (curated entries + MEMORY.md

index lines; project_briefing.md updates).

• Surgical edits to .agents/workflow.md / conventions.md.
• A dated report .agents/retrospectives/YYYY-MM-DD.md: sessions analyzed,

findings, what was applied, what was deferred and why.

• Advance the watermark: write .agents/memory/scout/.last-retrospective

as {"lastRun":"","analyzed":[]}, merging with any existing ids. Only after writing — never on a decline.

Fallback (non–Claude Code hosts)

If the parser exits with code 3, transcripts aren't accessible here. Ask the user to paste a session transcript or summary, then run steps 3–6 on that text (skip the watermark; note in the report that it was a pasted-transcript run).

Anti-memory-poisoning rules

• Never write without an explicit ack.
• Every durable fact cites a session id. No inventing.
• Record corrections as one-line lessons, not raw quotes.
• Bounded recall — reason over the digest, never raw .jsonl.

Common mistakes

• Writing before ack — forbidden; always propose-then-wait.
• Advancing the watermark on a dry run or a decline — only after writing.
• Treating a candidate correction as a fact without judgment — the digest

flags candidates; you decide.

• Reading raw transcripts into context — use the digest.

References

• references/transcript-schema.md — Claude Code JSONL + sub-agent layout.
• references/digest-format.md — the digest the parser emits.
• references/signal-taxonomy.md — signal definitions + thresholds.
• references/finding-to-target.md — finding→target mapping + safeguards.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arozumenko
• Source: arozumenko/sdlc-skills
• License: MIT

Install and usage instructions live in the source repository linked above.