retro

Files (2)

• SKILL.md
• session_digest.py · scripts/

SKILL.md (first lines)

# 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.

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding