session-retro
Installation
SKILL.md
Session Retro
Purpose
Look back at a session and improve what the next session starts from: navigation, automated checks, coding standards, steering files, tooling. The unit of improvement is the agent's environment, not the code that was written.
Workflow
- Read the primary sources of the session being reviewed: its transcript or logs if available, else the user's account. Default to the current session if none is named.
- Classify every observed failure or friction into exactly one improvement category:
- Navigation — the agent took long to find the right files or facts → a navigation pointer in
AGENTS.mdor an index doc. - Automated checks — a mistake a deterministic check could have caught → a lint rule, typecheck, test, pre-commit hook, or CI job. Read the repo's existing check commands first; a check that exists but is unwired or silently broken is the finding, not a reinvention. A repo with no guardrail at all is itself a finding.
- Coding standards — a mistake only judgment catches (cross-file consistency, style matching) → a rule in the standards doc a reviewer applies. Mechanical violations get deterministic checks, full stop; standards docs are reserved for judgment calls.
- Steering files — bloated
AGENTS.md/global instructions → move detail out to pointed-at docs; hunt instructions that change nothing about behavior (no-ops) and delete them. - Tool economy — expensive or token-inefficient tool usage → streamlined commands or better tooling.
- Information access — the agent lacked a crucial fact → tee logs, read-only access, or a reference doc.
- Skills — a skill misfired, was missing, or contradicted another → a fix routed to
skill-forge.
- Navigation — the agent took long to find the right files or facts → a navigation pointer in
- Present candidates to the user ordered by severity, each with its category and the concrete artifact it would change. Recommendations are advisory: do not edit, create tickets, run checks, or orchestrate follow-up work until the user explicitly approves a candidate.
- Apply only what the user approves.