retro

# Retro Propose improvements to the agent's **environment** based on where a session struggled. Propose only: change nothing until the user picks a candidate. Fix the environment, not the code the session produced (that is `code-review`). ## Steps 1. Create a task per step below, each with its completion criterion. 2. Get the session record: - No session named: use the current conversation. - Session named, or the current one is too long to recall reliably: run `python3 scripts/session_digest.py <id-or-path>` (`--list N --project <repo>` to find it). Digest each subagent transcript it lists when the struggle happened there. 3. Mark the **struggle moments**: errors, retries, hook blocks, long searches, oversized results, compactions, user corrections, wrong turns. Cite each by digest call number (`#12`) or by quoting the user. 4. Read the repo's existing checks (`Makefile`, `package.json` scripts, pre-commit config, CI workflows, `.claude/settings.json` hooks). A check that exists but is unwired or broken is the finding, in place of a new one. 5. Map each struggle moment to a candidate using the categories below. Drop any candidate you can't trace to a struggle moment. 6. Present candidates ranked by severity: cost of the struggle times how often it will recur. Each candidate states the moment, the fix, and the file it lands in. ## Categories - **Navigation**: the agent took long to find a file or fact. Fix: a pointer from a file it already reads. - **Automated checks**: the agent made a mistake a tool could catch. Fix: lint rule, type, test, pre-commit hook, CI job, or a Claude Code PreToolUse/PostToolUse hook. A repo with no **guardrail** (no pre-commit hook and no CI running lint/typecheck/test) is a finding in itself. - **Coding standards**: the reviewer missed a mistake. Classify it first. **Mechanical** (banned API, import shape, file location, fixed syntax) gets a deterministic check. **Judgement call** (cross-file consistency, matching surrounding style) goes in the repo's standards doc (`CODING_STANDARDS.md` or `CONTRIBUTING.md`). `code-review` reads only what the repo documents, so a new standards doc also needs a one-line pointer from the project `CLAUDE.md`. - **Steering bloat**: global `~/.claude/CLAUDE.md`, project `CLAUDE.md`/`AGENTS.md`, `.claude/rules/`, auto-memory `MEMORY.md`, SessionStart hook context, or model-invoked skill descriptions are large. Fix: move instructions into checks or standards, path-scope them into rules, or tighten a skill description or make it user-invoked. - **No-ops**: steering lines the agent already obeys by default, or ignored anyway. Fix: delete, or replace with a check. Treat each as a candidate for the deletion test, judged on one session. - **Skills**: a skill failed to fire, fired wrongly, or its instructions misled the agent. Fix: its description or body. - **Tool economy**: a tool call was expensive for what it returned (see oversized results in the digest), or the agent repeated a call. Fix: a cheaper command, a script, or a narrower tool. - **Information access**: the agent lacked information it needed. Fix: tee dev server logs to a file, read-only access to a service, a docs pointer. - **Sandbox and permissions**: a sandbox or hook block cost retries. Fix: the command pattern the agent should have used, or a sandbox/permission rule change for the user to make. ## Placement The implementer has the most context pressure: it explores, writes code and debugs. The reviewer gets a diff. Put rules where there is room to apply them. - Steering files (`CLAUDE.md`, `AGENTS.md`, SessionStart hooks) load into every session. Reserve them for navigation pointers and rules that apply to every task. - A recurring mistake becomes a failing check before it becomes prose. - Judgement rules go to the reviewer's standards doc, not `CLAUDE.md`. Extend an existing doc before writing a new one. - A user preference correction belongs in auto-memory as a `feedback` memory. Repo facts belong in the repo. ## Applying a picked candidate Load the matching skill before editing: - `CLAUDE.md` or `.claude/rules/` -> `authoring-claude-md` - A skill -> `skill-creator-primer` - Hooks, permissions or settings -> `update-config` Run a proposed check against the repo before letting it block anything.