Where should the fix land?
Label each piece of agent friction with its root cause and it points at the altitude (memory, docs, process, or upstream) where the durable fix belongs.
Two teams, same friction, different quarter
Two teams both start logging the friction their AI agents hit: the ambiguous asks, the stale docs, the flaky tools, the reruns.
The first team fixes everything at the level nearest to hand. Every recurring annoyance becomes a prompt tweak or a memory note; anything bigger becomes another paragraph in the context file. Three months later their agents run on bloated instructions nobody reads end to end, and the friction that mattered — the brief template that leaves scope undefined, the ad account whose structure fights every session — is still there, because no prompt tweak can reach it.
The second team asks one extra question per pattern: where does this fix actually belong? The “agents keep guessing our audience” cluster becomes a change to how work is briefed: a process fix, agreed in a team session. The stale-runbook cluster becomes a documentation fix with an owner. The one-off quirk becomes a memory note and nothing more. Three months later their instruction files are shorter than when they started, and the friction categories they fixed are trending down.
The difference is not logging discipline. Both teams logged. The difference is a routing question the first team never asked.
The core move: friction points at an altitude
When an AI-assisted session hits friction, the root cause points at a level where the durable fix lives. We call it the fix’s altitude; the available altitudes run from ephemeral to structural:
memory → skill/prompt → environment & config → documentation → the work material itself → process/workflow → upstream product or vendor
Naming the altitude turns a complaint into a routable fix. “The agent got the bid strategy wrong again” is a complaint. “The bid-strategy decision was never written down anywhere the agent could find it: a documentation fix, and here’s the runbook it belongs in” is a work item with an address.
Getting the altitude wrong fails in two directions. Under-targeting, a private memory note for what’s really a missing team doc, means the friction recurs for everyone who isn’t you: a recurrence tax on the rest of the team. Over-targeting (a new skill for a one-off, another paragraph in an already-bloated context file) is a maintenance tax on the artifact; the field has named the anti-patterns precisely: skill sprawl (16→48 skills in 15 days: “Adding skills is easy. … Management is the hard part.”) and context-file bloat (“a memory file that has stopped being read”, per this field note). The vendors have converged on the same gradient from the other end — demote ephemeral memory, promote durable learning to version control: Windsurf/Devin (“write it as a Rule or add it to AGENTS.md… rather than relying on auto-generated Memories”, docs), OpenAI Codex (“when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md”, best practices), Copilot memory’s deliberate 28-day expiry.
So the field knows both failure modes. What’s been missing is a routing instrument.
A fixed vocabulary that routes
Our working proposal: label each friction finding with exactly one root cause from a fixed vocabulary of ten labels in five groups: small enough to hold in your head, cause-shaped rather than symptom-shaped, and deliberately tool- and discipline-agnostic:
- Briefing:
ambiguous-instruction,missing-context,incorrect-context,changed-requirements - Documentation:
missing-documentation,incorrect-documentation - Work material:
work-material-friction - Tooling:
missing-access-or-tool,environment-friction - Agent:
agent-error
The group is the routing key. The moment a finding is labeled, it’s half-routed:
| Group dominant | The fix usually lives at | Typical artifacts |
|---|---|---|
| Briefing | process (how work is briefed) or a persisted memory | brief template, kickoff checklist, memory file |
| Documentation | docs | README, runbook/SOP, context file, spec |
| Work material | the material itself | code: the refactor the friction keeps pointing at; non-code: the account, board, or template restructure |
| Tooling | environment/config, or upstream | settings, MCP config, access grant, vendor ticket |
| Agent | prompt, skill, or guardrail | skill edit, hook, eval |
One honesty note up front: the groups are named for their fix destinations, so “the label half-routes the fix” is true by construction — a design choice, not an empirical discovery. The empirical claim underneath is that capture-time labels are accurate and consistent, which is exactly what we haven’t yet measured (more below).
Note what work-material-friction covers, because it’s where the vocabulary earns its discipline-agnostic claim. In code, it’s tech debt: the module every session trips over. Outside code, it’s just as real. Picture a marketing team whose agent audits a Google Ads account grown by accretion: three generations of naming conventions, paused campaigns nobody dares delete, keywords duplicated across overlapping ad groups. Every session, the agent burns its first stretch reconstructing which campaign owns what, and every recommendation carries a caveat. No prompt fix touches this; no memory note fixes it for the next person. The label is work-material-friction, always paired with the concrete material named (this account), and the altitude is the material itself: the restructure the friction keeps pointing at. The same pattern lives in tangled spreadsheets, CMS template messes, and support-macro libraries; a coding-agent-shaped loop has nowhere to put these.
Why fixed rather than emergent? Because for a team, the taxonomy is a coordination instrument, not a classification exercise. “The same friction across eight sessions is a process problem” only computes if all eight sessions labeled it the same way; distribution claims need a stable denominator; and trend lines (“is briefing friction down since we fixed the brief template?”) survive only if a label means the same thing in March and July. Emergent categories, each person coding their own, are the right call solo, but across a team they drift per person, and nothing aggregates without a reconciliation step nobody owns. We keep the emergent engine running in two places: an evidence-cited note beneath every label, and a periodic vocabulary review where the accumulated notes pressure-test the labels. The vocabulary is versioned; it is designed to change under evidence, not to be defended.
What already exists, honestly compared
We didn’t invent failure taxonomies, and the existing ones are good at what they’re for.
MAST (arXiv 2503.13657) is the reference fixed taxonomy: 14 failure modes in 3 categories, derived from 150 expert-examined traces and validated against a 1600+ corpus, with strong inter-annotator agreement (κ = 0.88). It classifies how multi-agent systems fail, built for research and benchmarking — closest to ours in discipline, different in object: we classify why human–agent collaboration friction happened.
The error-analysis school, Husain & Shankar’s evals methodology (evals FAQ, Jan 2026), argues the opposite of a fixed list: categories “should emerge from observed failure patterns… not predetermined query classifications,” and open-ended reading of your own traces is “the most important activity in evals.” We think they’re right at solo scale and that the trade flips at team scale, for the aggregation reasons above. Their reading discipline is load-bearing in our proposal either way; it’s what the evidence notes are.
Around these poles: the Four-Layer taxonomy (Greyling, May 2026) classifies which layer of the stack failed, attributing only ~9.9% of failures to model reasoning: most failures are harness problems (the harness is the scaffolding around the model), which is why our agent-error label is a residual, used only when the inputs were adequate (the harness-engineering school explicitly rejects the agent-blame default — fix the harness, not the agent: Osmani, Agent Harness Engineering). TraceProbe classifies error-handling actions in traces. Garg’s Feedback Flywheel harvests four signal types into team artifacts, the framework ours sits inside: his context ≈ our briefing + documentation groups; his failure arm is what our taxonomy decomposes. Factory Signals classifies session symptoms into auto-filed tickets; Braintrust Topics is the emergent school productized, re-clustering your traces daily.
Two honest readings of that comparison. First, most of these classify symptoms, layers, or destinations; ours classifies causes — that’s what makes the label a routing key, and it’s the actual novelty claim, such as it is. Second, and more important: MAST has measured labeling reliability and we have not. Inter-rater reliability on our ten labels is unmeasured, and we treat that as a prerequisite, not a footnote: the experiment (independent raters blind-labeling the same real entries, agreement reported whatever it says) is underway against entries from our own live trial, with MAST’s κ = 0.88 as the bar. Until it reports, this taxonomy is a working proposal with versioned labels, not a validated instrument. We’d rather tell you that than have you discover it.
We’re also supportive of every loop already running: Loop Engineering, Compound Engineering, agent-retro, AGENTS.md retrospectives, vendor memory systems, automated session reports. Keep them all; nothing here replaces them.
Why altitude is a team question
Here’s the gap those existing loops share: almost all of them are solo (one developer and their agent, or one vendor and its fleet). And the field’s own numbers say the expensive step isn’t watching: ~90% of teams instrument agent traces, but only ~37–52% systematically evaluate them (LangChain State of Agent Engineering, Jun 2026). The unclaimed layer is team-level synthesis, and that’s precisely where altitude starts to matter, for two reasons.
Aggregation reweights priorities. One person’s ten-minute annoyance is noise; nobody rationally fixes it. The same label across eight sessions and five people is one of the team’s largest costs, and only the aggregate view can see it. Aggregation is also what the fixed vocabulary buys: the counts only add up if everyone used the same labels.
The highest altitudes are team-owned. An individual can fix their own memory, prompts, and config. But process changes, cross-tool judgment calls, budget for tooling, upstream escalations — the altitudes where the biggest recurring friction usually points — are decisions no individual can make alone. This is also why we think a human seat at synthesis persists however good models get: the fixes land in artifacts humans own and answer for: briefs, processes, budgets, team agreements. That’s a claim about organizational authority, not model capability. And it’s a seat in the loop, not a gate on the pipeline: agents should detect, record, cluster, and draft freely; humans add the routing judgment and carry the accountability.
If your team already runs a continuous-improvement ceremony, this slots into it: the aggregate friction picture arrives, the team asks “where does each fix land?”, and each pattern leaves with an altitude and an owner. Not a new ritual — a retrospective with better inputs. ML engineers call the reading error analysis; teams call the venue a retro.
What would change our minds
This is a discussion paper, so here is what we’re genuinely unsure about:
- Reliability. If the inter-rater experiment reports poor agreement, the boundary rules (or the labels themselves) are wrong, and we’ll revise them under the version stamp rather than defend them.
- Size. Ten labels is inherited, not derived. MAST runs 14; Four-Layer runs 4. Our label distribution after a quarter of real entries is the evidence that keeps or reshapes it.
- Missing modes. Inter-agent friction (subagent handoff loss, orchestration failures) currently files under
environment-friction; real occurrences may demand a label of its own. - Non-code review scope. We scope reviews by where fixes would land: the repo for most dev work; “account,” “workspace,” or “engagement” outside it. Those non-code boundaries are proposals we want tested against real teams.
- Capture-time feasibility. Can busy teams label causes in the moment, or must labeling happen at review? Teams who try it would settle this faster than our theorizing.
If you run any version of this loop (emergent categories, a vendor pipeline, a plain spreadsheet), we’d like to hear where the routing table breaks. Especially if you can show us a friction pattern that doesn’t point at an altitude at all: ai-discussion@teamretro.com.
Next chapter: The report exists. The room doesn’t. — why routing the fixes is a team decision, and what the team does when the friction report arrives. Part of the AI agent retrospectives guide.