session-friction-retro

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:

1. 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.
2. 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

1. Acquire the session (hybrid — see below). Default to introspection; use a trace if offered.
2. 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).
3. Apply the two guards. Keep only rows with a fired signature and a cheaper alternative.
4. 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).
5. 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.
6. 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.