minhtran3124/agent-harness/session-retro

Session Retro — change the environment, not the code

compound records what a session learned. This skill asks what in the repo let the agent stumble, and which lever would stop the next session stumbling the same way? It reads the session, not the code, and proposes rather than edits: each environment change taxes every later session, so the user decides which are worth it.

If nothing struggled, say so and stop; rules manufactured from a clean run make the harness worse.

The record

Default to the current session. For a past one, the transcript is ~/.claude/projects/<project-slug>/<session-id>.jsonl. If earlier turns were compacted, say so: a summarized stretch cannot evidence a moment, so its lack of struggles is unknown.

From struggle to lever

List the moments of friction — long searches, repeated mistakes, a reviewer catching what a tool could have caught, expensive tool calls — each with a pointer to where it happened. Every candidate traces to one. The class of each decides the lever:

Prefer a check whenever the violation is mechanical: a check can fail, a sentence cannot. Prose is for real judgement calls only. A rule without paths: frontmatter loads every session, so adding one is a cost to everyone. If a mistake class has no hook, test, or CI job at all, report the missing guardrail as its own finding.

Before proposing, filter for recurrence: would this fix have helped most recent sessions, or only this one? Look in docs/solutions/INDEX.md, docs/harness-experimental/improvement-backlog.md, and rules/. A recorded match is evidence of recurrence — cite it and raise its priority rather than duplicating it. An existing guard that should have fired turns the finding into "why did it not fire?". A one-off with no prior record is reported as one.

Report

Rank by expected recurrence times the cost each recurrence carries. Per candidate give the struggle with its pointer, the class, the proposed lever, the target path, its ongoing cost, and the evidence tier it would reach (traceability, provenance, or truth). List steering lines that look dead separately, flagged for review. Name the limits that apply to this run (one session cannot show an older rule is obsolete; its topic may be overweighted).

Then stop. Nothing changes until the user picks candidates. Approved mechanical items become improvement-backlog.md rows or a feature-intake task; durable knowledge goes through compound.

Verifies: each candidate cites a moment in the session record and a classified lever. Does not verify: that the struggle would recur, or that the proposed fix prevents it.