| name | session-friction-retro |
| description | Harness-agnostic post-session friction forensics. Run at (or near) the end of a session to
audit THIS session for avoidable frictions that had a cheap alternative, and emit a ranked
report mapping each friction to a concrete cheap harness lever (skill / MCP tool / permission /
prompt-CLAUDE.md / tool-schema / memory / delegation-policy). Use when the user wants to know
what the session cost in wasted turns/tokens and what cheap harness change would stop it
recurring.
|
| disable-model-invocation | true |
| stage | proving |
Session Friction Retro
Audit the current session against the A–H friction rubric and produce a ranked list of
harness changes — each change cheaper than the friction it removes. The audience is the person
who builds the harness (skills, hooks, MCP servers, tool schemas, permissions, system prompt /
CLAUDE.md), so every finding ends in a concrete lever they can pull, never "the agent should
try harder".
Harness-agnostic by design: the default path leans on what the agent can still see in its own
context, not on any one harness's trace-file format. A thin optional trace hook sharpens it when
a harness exposes one.
The rubric is the engine
Read references/friction-rubric.md and walk it row by row.
It defines 34 frictions across 8 classes (A context/token economy · B tool-call quality ·
C control-flow/looping · D search/discovery · E communication/clarification · F verification
hygiene · G harness/config meta-layer · H memory/cross-session). Each row carries:
event signature → cost paid → cheap alternative → harness lever.
Two hard guards from the rubric, applied to every candidate finding:
- Signature-first. A row becomes a finding only if its event signature actually fired this
session and a cheaper alternative existed at the time. If either is missing, drop it —
that is the guard against a report that merely re-narrates what the agent already said.
severity ≠ confidence. Rank by cost paid × confidence the signature is real, and report
the two separately. A high-cost finding you are unsure of is not the same as a cheap certain one.
Workflow
- Acquire the session (hybrid — see below). Default to introspection; use a trace if offered.
- Walk the rubric. For each of the 34 rows, ask: did this signature fire? Collect concrete
evidence (the actual tool call, error string, file path, count, ordering).
- Apply the two guards. Keep only rows with a fired signature and a cheaper alternative.
- Map to levers. For each surviving finding, name the harness lever and a specific fix
(not the lever category — the actual rule/permission/skill to add).
- Rank. Order by
cost × confidence. Weight class G (meta-layer) up on ties — those
levers are usually the cheapest and highest-leverage for a harness-builder.
- Emit the report in the format below.
Trace acquisition (hybrid)
Default — introspection (works on any harness). Reflect over the session you can still see:
your own messages, tool calls, tool results (including errors), and their ordering. Most rubric
signatures are detectable this way — repeated identical errors, re-reads, validation failures,
broad greps, missed clarifications, unrecorded lessons. Be honest about what is outside the
visible window: if the session was compacted, say which span you could not inspect.
Optional — thin trace-provider hook. If a scripts/get-trace.sh in this skill dir prints a
path to a machine trace (JSONL of events: role/type, tool + params, result with error flag,
ordering), use it to sharpen signatures introspection can only estimate (exact tokens, full
ordering across a compacted span). A trace is never required — without one, fall back to
introspection silently; its absence lowers precision, not function.
Output format
# Session Friction Report — <one-line session descriptor>
**Trace source:** introspection | trace (<provider>) | introspection (compacted span N–M not seen)
**Frictions surfaced:** <count> · **Net cheap fixes proposed:** <count>
## Ranked frictions
### 1. [F<id> · class <A–H>] <short name> — cost: <turns/tokens> · confidence: <hi/med/lo>
- **What fired (this session):** <concrete evidence — the actual call/error/path/count>
- **Cost paid:** <turns or tokens wasted, and why>
- **Cheap alternative (at the time):** <what should have happened>
- **Harness lever → fix:** `<lever>` — <the specific rule / permission / skill / schema to add>
### 2. ...
## Top cheap fixes (do these first)
1. `<lever>` — <fix> (removes F<id>; cost paid ≈ <…>)
2. ...
## Not surfaced / out of window
- <rubric rows checked and cleared, or spans not inspectable> — keeps the report honest.
Guidelines
- Concrete or it does not ship. Quote the real error, the real path, the real count. A finding
with no evidence is a platitude — cut it.
- Levers, not scolding. Every fix names a lever from the rubric's fixed vocabulary and the
specific change. "Be more careful" never appears.
- Cheaper-than-the-friction. Only propose a fix whose cost to apply is below the friction it
removes; say so when it is close.
- Stay in lane. If a finding really needs multi-session trend data to judge, note that and
stop — do not grow trend-tracking into this skill.
- Harness-agnostic phrasing. Describe levers in portable terms (a permission allow-rule, an
MCP tool, a system-prompt rule) so the same report reads on Claude Code, opencode, or a custom
runner. Name a harness only in the concrete fix, not in the analysis.
