Retro

Coding Session Retrospective

Inspect a real coding session and propose improvements to the agent's environment, not the product code. The goal is to make the next run easier to navigate and harder to get wrong.

This is human-in-the-loop. Present findings first; do not edit steering files, standards, hooks, CI, or skills until the user chooses which findings to apply.

When to Use

Use when:

• A coding session was unusually long, confusing, or error-prone.
• The user asks to review recent agent sessions.
• A bug or repeated mistake suggests a missing guardrail.

The default target is the current session. If the user names a count or date range, inspect that exact range. If session history is unavailable, say so and review the repository evidence only.

Sources

Read the real sources before judging:

• Session transcript and tool output, using session search when available.
• AGENTS.md, CLAUDE.md, GLOSSARY.md, GLOSSARY-MAP.md, and repository-local steering files.
• CODING_STANDARDS.md or equivalent review guidance.
• Existing package.json, pyproject.toml, Makefile, task runner, hooks, and CI workflows.
• The final diff, test output, and any unresolved warnings.

Do not infer a recurring mistake from one suspicious line. Tie every finding to concrete evidence from the session or repository.

Review Lens

Rank findings by severity and expected leverage. For each, record:

Finding: what happened
Evidence: session message, command, file, or diff
Prevention: the smallest environment change that would stop it
Owner: repo check | agent skill | steering file | tool | documentation
Cost: maintenance and false-positive risk

Inspect these categories:

Skill learning loop

Treat a human correction as training data for the workflow, not as a one-off preference:

1. Save the agent's output before editing it.
2. Make and save the human-edited version against the same input.
3. State what decision the edit reflects that the skill did not encode.
4. Rewrite the rule as a decision procedure, including when it does not apply.
5. Rerun the original input and compare the result with the edited version.

Do not add vague rules such as “make it better” or blindly encode every edit as a universal instruction. Keep only lessons that held up on real work. If a lesson is mechanical and stable, prefer a linter, test, hook, or CI check over more prose. Keep shared rules in the main skill and context-specific rules in a linked reference or style file so the skill does not grow indiscriminately.

Navigation

Could the agent have found the right file, command, dependency, or domain term sooner? Prefer a short navigation pointer or a GLOSSARY.md entry over a large instruction block.

Automated checks

Could a deterministic test, linter, typecheck, pre-commit hook, or CI job catch the mistake? Read the existing check commands first. If a check exists but is not wired or is silently broken, fix the wiring rather than inventing another check.

Mechanical mistakes belong in automation: banned APIs, required file locations, schema shape, generated-file drift, import rules, or formatting. A sentence saying “remember to do this” is not a guardrail.

Coding standards

Reserve CODING_STANDARDS.md for judgement calls that automation cannot decide: cross-file consistency, design fit, naming in context, and review expectations. Put reviewer-facing rules there, not implementation trivia.

Steering files

Remove no-op advice and move detailed procedures into skills or docs. Keep AGENTS.md and equivalent files short, navigational, and high-signal. Check for stale names such as CONTEXT.md; this repository uses GLOSSARY.md when that convention applies.