Routing a Failed Repair to a Human Queue: Codes, Ownership

Five codes cover the practical cases. Each has a single owner type, one required action and a deadline that starts at the failure timestamp, not at the moment someone notices the item.

The relative deadlines carry the interesting decision. Tool defects get a tight clock because they usually break many callers, not one. Policy blocks get the tightest because a guardrail firing is a signal about an action the system should or should not be able to take, and leaving it open is a standing risk. Prompt ambiguity gets the longest clock because identifying and fixing it is genuine writing work, and rushing it produces prompt churn that breaks other cases.

The 1-day clock on UNMATCHED is the design rule that keeps the whole scheme honest. If unmatched items sit, the taxonomy silently rots and everything drifts back into a general queue. Triage owns the taxonomy, so a misfit is triage's work, not the requester's.

A reason code is only useful if it is derived from evidence. Without a record of what happened inside the run, three people will assign three different codes to the same failure.

Production agent failures are hard to debug precisely because a single run involves multiple model calls, tool calls, retrievals and state changes, and any step can introduce the error while a flat log leaves every step disconnected (Braintrust). The same source gives the canonical example: a support agent gives a wrong refund answer, the final log shows only the confident wrong answer, and the actual cause is a retrieval step returning an outdated policy document. That distinction is exactly the difference between DATA_QUALITY and PROMPT_AMBIGUITY.

The broader workflow literature makes the same point: most agent failures are not only prompt failures, and a bad answer can come from weak instructions, the wrong tool call, missing context, a bad retrieval result, a handoff to the wrong specialist, a schema mismatch or a guardrail that fired too late (Medium, No Time). Treating the prompt as the whole system is how a TOOL_DEFECT becomes a prompt rewrite that never fixes anything.

So the rule is: no code without a trace. The three-question test below turns a trace into a code in under a minute.

1. Did the step that failed do what it was told, given what it received?
   No  -> check the input to that step.
         Input was correct and task clear -> TOOL_DEFECT
         Input was stale/wrong/missing     -> DATA_QUALITY
   Yes -> go to 2.

2. Was the task genuinely ambiguous across plausible readings?
   Yes -> PROMPT_AMBIGUITY
   No  -> go to 3.

3. Did a guardrail or policy refuse it?
   Yes -> POLICY_BLOCK
   No  -> UNMATCHED (triage owns it within 1 business day)

Note the ordering. Input checks come first because they are objective: the trace either shows a stale document or it does not. Ambiguity comes second because it is a judgment call, and it should only be reached once the mechanical causes are excluded. Policy comes third for the same reason.

Assigning a code is easy. Making ownership stick is the operational work. Four rules do most of it.

One owner, never a team name. "Data team" is not an owner. The item needs a named person or a named on-call rotation. Severity and priority models in incident response depend on the same discipline: declaring a severity should immediately determine who is paged, whether an incident commander is required and what follow-up is owed, because responders should be mitigating, not negotiating who joins (Rootly). A repair queue item should behave the same way.

The owner at assignment stays the owner for the first cycle. Reassignment is the most common way a queue stalls. If the prompt owner believes the cause was data, they log that as a comment with the trace evidence and the assigned owner makes the first decision. Only the owner can return to triage with the UNMATCHED code attached.

Code ownership maps to the code. Where the repository already has code owners for the prompt file, the tool wrapper or the data pipeline, the reason code should map to the same owner. This is how quarantine systems attribute flaky tests: webhooks carry the file path, the code owner and the reason the test was marked flaky, and those drive the alert to the owner and the ticket creation (Trunk). Repair routing can reuse that mapping instead of inventing a second one.

Every code is verifiable. Before a code is assigned, the failure must reproduce against the same code and inputs, or the trace must show a non-reproducible condition such as a timeout or rate limit. The distinction matters: re-running on the same commit and getting a pass where the first run failed indicates a non-deterministic problem, while a consistent failure indicates a real defect (ContextQA). The same logic separates a repair that failed because of ambiguity from one that failed because of timing.

Measure the deadline from failure_timestamp, the moment the repair attempt failed, not from when the item was read. Store it alongside the code:

{
  "item_id": "rep_8842",
  "failure_timestamp": "2026-03-04T14:32:01Z",
  "reason_code": "TOOL_DEFECT",
  "owner": "integrations-oncall",
  "required_action": "fix contract: order_lookup returns null for guest orders",
  "due_at": "2026-03-06T14:32:01Z",
  "trace_span_id": "span_9f2a",
  "escalation": ["owner_lead@t+1d_overdue", "queue_owner@t+2d_overdue"]
}

Two escalation steps are enough. At one day overdue, the owner's lead is notified. At two days overdue, the queue owner reassigns or explicitly accepts the delay in writing. Auditing standards in other domains treat the acceptance of risk as an explicit, documented judgment rather than an implicit one; audit sampling guidance, for example, frames the justification for accepting uncertainty as resting on a stated relationship between cost and the consequences of error (PCAOB AS 2315). Overdue repairs deserve the same treatment.

Now a worked example with numbers. Suppose one queue receives 300 failed repairs in a week:

Read that table as a worklist. Prompt and data together are 60% of volume, so those two owners get the most capacity. Data quality is the worst on-time performer at 64%, which is the signal to look at whether the data owner has the authority to correct records or only to report them. And 13% unmatched is high; a healthy figure is a few percent, and every unmatched item is evidence the classifier needs a new branch or a clearer definition.

The comparison that matters for capacity planning is code mix, not raw volume. A week where the total drops from 300 to 250 but UNMATCHED rises from 13% to 25% is a worse week, because it means routing is degrading and the apparent improvement will reverse.

Turning recurring failures into permanent coverage is the last step. The practice that works is to capture the failed trace, label the failure mode, promote it into a versioned regression dataset and gate releases on a scorer for that pattern (Braintrust). The reason code you already assigned is the label. Regression testing exists because a prompt change that fixes one complaint can quietly break ten other answers (Langfuse), which is why each PROMPT_AMBIGUITY fix should ship with the failing case attached.

Too many codes. Ten codes produce inconsistent assignment and a routing table nobody maintains. Five is enough for most teams; add a sixth only after UNMATCHED has held a consistent pattern for several weeks.

Codes assigned after the fix. If the reviewer fixes first and codes second, the code records what the fixer did rather than the cause. Assign the code at failure time, in code. The denial-analysis workflow is explicit that categorization belongs at the initial review and that programs stay reliable only when the workflow requires it: no root cause code, no move to appeal or correction (Revecore).

A general queue as a fallback. A fallback queue without a deadline is where items go to be forgotten. The fallback is triage with a one-day clock, and triage's job is to change the taxonomy.

Treating the queue as the solution. Quarantine is a tool, not the whole solution: without a process for fixing or removing items it produces a growing backlog and the same erosion of trust it was meant to prevent (Trunk). A repair queue with no deadline discipline is that backlog with better labels.

Using the code as a blame instrument. Reason codes route work; they do not score people. The moment a code becomes a performance metric, it gets assigned defensively and stops being evidence.

If the item is a policy block, the safety reviewer needs the full record. Agent audit logging practice is a useful reference: each action is recorded as a structured entry with a timestamp, the invoker, the source and the outcome, so any entry can be traced back to the request that caused it (Nylas). A POLICY_BLOCK item arriving without that record forces the reviewer to guess, which is how a one-day deadline becomes a week.

For teams running this across several model providers, the mechanics of the repair loop should not depend on which model produced the output. Quanta Inference (https://quantaintelligence.ai/inference) exposes text, image, video, audio and embedding models through one OpenAI-compatible API key, so the failure-handling code that emits reason codes stays the same whichever model is behind the call.