borghei/Claude-Skills / workflow/session-retro
session-retro
VerifiedReview a coding-agent session and turn its failures and waste into ranked fixes to the agent's environment. Use when a session went slow or wrong, after a messy agent run, or to tune CLAUDE.md or AGENTS.md.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.9 KB |
| assets/retro_template.md | markdown | 1.5 KB |
| assets/sample_action_items.json | config | 1.9 KB |
| assets/sample_session.jsonl | other | 34.7 KB |
| references/finding-categories.md | markdown | 9.0 KB |
| references/fix-placement-and-steering-style.md | markdown | 6.3 KB |
| references/transcript-sources.md | markdown | 3.5 KB |
| scripts/action_item_linter.py | script | 8.4 KB |
| scripts/session_log_analyzer.py | script | 11.9 KB |
references/fix-placement-and-steering-style.md
View on GitHub# Fix Placement and Steering-File Style
A retro finding is only as good as where its fix lands. The same lesson written into the
wrong file either never reaches the agent or reaches it on every turn when it is needed on
one. This reference covers where to put a fix, how to rank fixes, how to write steering
lines, and how to check that a fix worked.
## The placement ladder
Pick the highest rung that can carry the fix. Higher rungs work without the agent
remembering anything; lower rungs cost context on every session.
| Rung | Mechanism | Cost per session | Use when |
|------|-----------|------------------|----------|
| 1 | Deterministic check: lint rule, type rule, test, pre-commit hook, CI job | Zero until it fires | The mistake has a fixed shape a program can detect |
| 2 | Better tool: wrapper script, summary flag, clearer error message | Zero until used | The agent used the right tool badly, or the tool's output misled it |
| 3 | Environment change: allowlist, ignore file, log teeing, safe named target | Zero | Friction or missing information, not a decision |
| 4 | Standards doc read at review time | Only during review | A judgement call a reviewer should enforce |
| 5 | Pointer in a directory-level steering file | Only when working in that directory | Navigation or convention specific to one area |
| 6 | Line in the root steering file (`CLAUDE.md`, `AGENTS.md`) | Every turn of every session | Repo-wide fact the agent needs before it starts |
| 7 | Skill description or new skill | Description on every turn; body on demand | A repeatable multi-step procedure |
Two consequences matter most:
- **Mechanical rules belong on rung 1.** "Never import from `internal/` outside its package" written in `CLAUDE.md` is followed most of the time. The same rule as a lint check is followed every time and costs nothing until broken.
- **Review-time rules belong on rung 4, not rung 6.** The implementing agent carries the most context pressure: it is exploring, writing, and debugging at once. The reviewer receives a diff and has room to apply a long list of rules. Put standards where the reviewer reads them.
## Ranking the action list
Rank by expected cost removed, then by cost to fix. A simple score works:
```
priority = severity (high 3, medium 2, low 1)
x recurrence (1 = this session only, 2 = seen before, 3 = will hit every session on this task type)
/ fix effort (1 = one-line edit, 2 = small script or config, 3 = a new check or tool)
```
Ship the top items, at most seven. A retro that lands three fixes beats one that lists
fifteen and lands none. Everything else goes to a **parked** list with the trigger that
would promote it ("promote if it recurs in a second session").
## Writing steering lines
The root steering file is read on every turn. Each line competes for attention with the
task itself. Write it accordingly.
- **One fact or instruction per line, imperative mood.** "Run tests with `make test`." Not "It is generally a good idea to use the make target when running tests."
- **Lead with the trigger.** "CLI flags: `src/exporter/main.py` `build_parser()`." The agent scans for the situation it is in.
- **State the positive target.** "Use `make clean` to remove build output" steers better than "Do not run `rm -rf build`", because a prohibition still puts the forbidden command in front of the agent. Keep a bare prohibition only for a hard safety line, and pair it with the alternative.
- **Point, don't paste.** Link to the doc or skill that holds the procedure. The pointer's wording decides whether the agent follows it, so name the situation it covers.
- **Do not cache what one command reveals.** Script names in `package.json`, flags in `--help` and the directory layout are already discoverable. Restating them creates copies that go stale. Write down what looking cannot reveal: the unwritten convention, the reason behind a choice, the trap.
- **No filler.** Cut "please", "make sure to", "it is important that", "always remember". They add tokens and no information.
- **Delete as readily as you add.** Every retro should ask which existing lines did nothing this session. A line that never changes behaviour is cost with no return.
### Before and after
| Before | After |
|--------|-------|
| It's important to always make sure you run the full test suite using the Makefile because running pytest directly can sometimes cause import problems. | Tests: `make test`. Bare `pytest` fails on import (needs `PYTHONPATH=src`). |
| Please be careful not to edit generated files. | `src/gen/` is generated by `make codegen`; edit `schema/*.yaml` instead. |
| Remember to check the coding standards before submitting. | (delete — move the standards to the reviewer's checklist) |
| Don't use `requests` directly. | (delete — add a lint rule banning `import requests` outside `src/http/`) |
## Where common fixes land
| Platform or tool | Steering file | Settings / allowlist | Per-directory steering |
|------------------|---------------|----------------------|------------------------|
| Claude Code | `CLAUDE.md` | `.claude/settings.json` | `CLAUDE.md` in the subdirectory |
| Codex, Aider, Jules and other AGENTS.md readers | `AGENTS.md` | The tool's own config | `AGENTS.md` in the subdirectory where supported |
| Gemini CLI | `GEMINI.md` | The tool's own settings | `GEMINI.md` in the subdirectory |
| Cursor | `.cursor/rules/*.mdc` | Editor settings | Scoped rules with globs |
| Any | Pre-commit config, `Makefile`, CI workflow | — | — |
Check the platform's current documentation before relying on a per-directory file; support
varies by version.
## Verifying a fix
A fix is a hypothesis. Name the observation that would confirm it before shipping:
- **Navigation fix:** on the next session of this task type, the first relevant file is opened within a handful of calls and the empty-search detector stays quiet.
- **Check fix:** introduce the original mistake on a scratch branch; the check fails.
- **Tool fix:** the same command's output drops below the oversized threshold.
- **Permission fix:** the blocked pattern no longer appears in the next transcript, and nothing destructive was allowed.
- **Skill fix:** the skill fires on the original prompt without being named.
Re-run `session_log_analyzer.py` on the next comparable session and compare findings. A
fix whose detector still fires was placed on the wrong rung.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |