What a good friction record looks like

Why records, not memories

One session’s friction is noise. The same friction across eight sessions is a pattern your team can fix — but only if those eight sessions left behind records you can actually read together: consistent (same schema, so they’re comparable) and honest (evidence-cited observations, not vibes).

Neither happens by default. The moment friction occurs is the moment of maximum information about it — the exact stale line in the runbook, the exact parameter the brief left open. That information decays fast. The agent normalizes its own workaround within a few turns, and at session end the signal is gone unless something wrote it down; whatever a subagent figures out “vanishes the moment it returns” (Hindsight, May 2026). This chapter is about the writing-down.

How friction gets noticed

Before anything can be recorded, it has to be noticed. Four channels, and they see different things:

The agent notices itself struggling. Retry loops, backtracking, re-reading the same file or re-querying the same analytics view, a guess forced by a gap in the brief. Production platforms have converged on essentially this behavioral-signal list (Factory Signals, Jan 2026). The cheapest channel, with two honest limits: it’s blind to absent things (a retry loop is felt; a document that never existed produces no signal), and self-observation outruns self-diagnosis — models localize their own agentic errors poorly even on curated traces (~11%, TRAIL). So the in-session job is to observe symptoms and cite evidence, holding the diagnosis loosely.

A second agent reviews the transcript. A fresh reviewer catches what the working agent normalized. More objective; costs a second pass and carries its own judgment errors.

A human corrects the agent. Still the dominant sensor: an 8-week production study found ~70% of silent agent failures were first caught by a person noticing something felt off — not by unit tests, health checks, or governance audits (arXiv 2606.14589). Every correction (a reviewer’s “no, I meant…”, a stakeholder re-explaining the brief mid-audit) marks exactly where context diverged from intent, and the agent can capture it in the moment at zero extra process cost.

Telemetry. Tool-error rates, permission denials, loop counts, long durations. Automatic and unbiased, but shallow: it knows that something happened, not why.

The strongest setups triangulate: telemetry flags where to look, a review pass explains why, and human correction fills in the class of problem no self-signal can reach. Whatever mix you run, what survives should be the same thing: a record.

What makes the agent record it

An agent won’t record friction nobody told it to look for. Most friction goes unrecorded not because it wasn’t noticed but because nothing made capture happen. Four mechanisms, differing mainly in what guarantees firing:

• A skill: a versioned, written procedure the agent executes at session end. Carries the schema and the honesty rules, so what fires is consistent: the same procedure works on a refactor and an ads-account review. Weakness: invocation is probabilistic; it can silently never fire.
• A hook: the harness itself triggers or reminds (a session-start injection, a session-end trigger). Deterministic (the only option that depends on nobody remembering anything), but blunt (it fires on the two-minute session too) and platform-bound.
• A convention line: one standing instruction in the scope’s context file, or its non-code twin, a step in the team SOP: “end every substantial AI-assisted session by logging friction.” Zero infrastructure, but it leans entirely on the model honoring one line among many, and it decays as the file grows; the named failure mode is the memory file that has “stopped being read” (anti-patterns field note).
• A command: a human-typed /retro at the end of a feature branch or a triage shift. Deliberate and precisely timed; the weak link is human memory.

These compose; layer them. A deterministic trigger (hook, or an end-of-shift SOP step), a procedural payload (the skill), and a convention line that names the practice as a norm — pick at least one trigger, two is better. Even vendors have landed on the instinct: OpenAI’s Codex guidance reads “when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md” (best practices).

The anatomy of a good entry

A record is the contract between the session that noticed the friction and everything downstream — synthesis quality is capped by record quality. Four load-bearing parts:

1. An evidence-cited moment, with its cost. What happened, when, and the observable consequence, specific enough that someone who wasn’t in the session could act on it. Cost means redone work, wasted time, wrong output; a record without cost can’t be ranked later. Agent-estimated cost is soft: mark it (est.) rather than faking precision.

2. Exactly one root-cause label from a fixed ten-label vocabulary. Fixed vocabularies can be labeled reliably (MAST reached κ = 0.88 on 14 failure modes; see arXiv 2503.13657); free-form categories drift per person and stop aggregating. The ten:

• ambiguous-instruction: the ask left a key parameter open (audience, scope, definition, time window) and forced a guess
• missing-context: a standing fact the team knows but didn’t share
• incorrect-context: information provided was wrong
• missing-documentation: a doc that should exist doesn’t (no README, spec, runbook, or SOP)
• incorrect-documentation: a doc exists but is stale or wrong, and was relied on
• work-material-friction: the material being worked on made the work slow or error-prone: tech debt or confusing structure in code; a tangled account, board, spreadsheet, or template outside it (always name the concrete material)
• missing-access-or-tool: a needed connector, permission, or tool wasn’t available
• agent-error: the agent’s own mistake (wrong assumption, stale knowledge, a bug it introduced)
• changed-requirements: the ask changed mid-session and work was redone
• environment-friction: tooling failures, timeouts, sandbox or platform issues

One label per finding keeps the distributions honest: pick the closest fit, note the strain in the evidence, never invent a label mid-entry. Three boundary rules do most of the disambiguating work. The agent-knowable test: was the fact findable anywhere the agent could reasonably look? Found nowhere it should have been → missing-documentation; supplied only later, by a person → missing-context. Agent-error is the residual: use it only when the inputs were adequate and the agent still erred; if the error traces to a bad input, label the input. And ambiguity versus movement: if clarifying revealed what was always meant, it was ambiguous-instruction; if the goal genuinely moved, it’s changed-requirements.

3. A ticket-sized fix, naming its altitude. The altitude is the level the fix targets: memory, skill, environment, docs, the material itself, process, or upstream. A friction record with no fix attached is a complaint.

Here’s a complete entry from a non-code session, a monthly ads-account review:

- **[missing-context]** The brief didn't say the French campaigns were deliberately
  paused for Q3; ~40 min (est.) auditing a "broken" campaign that was fine.
  → Fix (altitude: process): add campaign-status flags to the monthly brief template

A moment, a cost with an (est.) marker, one label, a fix somebody could pick up next week. Compare the unusable version of the same observation, “the brief was confusing”: no moment, no cost, no next step. Vagueness is itself a failure mode.

4. Permission to say nothing. “Nothing notable” is a valid and useful answer; a log padded with manufactured findings drowns the real ones.

One more design point: recording should be ungated — an agent that needs permission to record friction under-reports. Let it file freely, and let human feedback land as correction after the fact: additive signal from the person who was in the session too, not a checkpoint the loop waits on.

The never-log rules

Records outlive their sessions: they get committed, shared, and aggregated. Some things never go in:

• Secrets, credentials, tokens, or API keys, in any form, even partial.
• Customer data or personal information.
• Unreleased business numbers or confidential figures — describe the effect, not the data.
• Above all, people. Never a name, a role, or anything that identifies who caused a gap. Describe the gap and what it cost: “the brief left the audience open,” not “X’s brief.” Entries critique inputs and systems, not people — the same discipline a good retrospective runs on, and what makes the log safe to read together.

Critiquing the inputs is expected: unclear briefs, missing context, and late requirements are usually where the actionable material lives. The agent should critique itself with the same honesty. If a scope’s friction can’t be described without sensitive context, keep that scope’s entries private and share only the aggregated brief.

Where the log lives

One log per review scope — the boundary where fixes land. For most dev work that’s the repo: its docs, config, and conventions are repo-homed, so its friction log is too. Outside code, the scope is the ads account, the support inbox, the client engagement; keep the log in that workspace’s document home. A record filed outside its scope is one the eventual fix-owner never finds; an entry written to a scratch directory dies with the session.

What must stay identical everywhere is not the storage but the shape: the schema, not the storage, is what makes entries aggregate later. That’s the whole team angle of this chapter: comparable records, across people, agents, sessions, and tools, are what make team-level aggregation possible at all. Adapt the storage freely; guard the schema.

What comes next

A pile of good records is raw material, not insight. The next chapters take it from here: choosing the altitude of each fix (the difference between a memory note and the refactor the friction keeps pointing at); synthesizing entries into a one-page brief the team can read together; and the ceremony where humans and the log meet — the retrospective, with the agent’s records as a participant’s input. The loop is one instance of the Feedback Flywheel: harvest learnings back into the artifacts that supply context (martinfowler.com). And the entry discipline is error analysis, “the most important activity in evals” (Husain & Shankar, evals FAQ), moved to the cheapest possible moment: while the session that hit the friction is still open.

Everything above works with a text file and any capable agent. If you’d rather not build the template yourself, the free ai-session-retro skill implements this entry shape end to end; the quick-start post walks through installing it in about ten minutes.

Next chapter: Where should the fix land? — the altitude problem, and the routing table.