reopt-decision-traceability

---
name: reopt-decision-traceability
description: When agent decision paths must be traceable after the fact. Structured logging, distributed tracing. Responding to audit requirements; attributing the cause of an incident.
---

# Decision Traceability

OCLS phase: **SHARPEN** · Record judgment rationale, choices, and collaboration paths as structured logs.

## Core rules

- Equip every agent and module with structured decision logs.
- Required log fields: input context, chosen action with rationale, rejected alternatives, called modules and their result, handoff target and reason.
- Standardize log format as JSON or OpenTelemetry spans, and trace inter-agent causality via a trace ID.
- Separate metrics that need real-time alerts (guardrail blocks, escalations) from metrics suited to batch analysis (quality distribution, cost trends).

## Judgment question

**Can the rationale of this agent's decision be explained after the fact?**

## Application check

1. Does the decision log include every required field?
2. Is the log structured (JSON / OTel)?
3. Can you follow inter-agent causality via a trace ID?
4. Are real-time and batch-analysis paths separated?

## Code example

```json
{
  "traceId": "tx-4521",
  "spanId": "resp-1",
  "parentSpanId": "intake-0",
  "agent": "response",
  "timestamp": "2026-04-17T10:23:11Z",
  "input": {
    "category": "shipping-delay",
    "sentiment": "frustrated",
    "priorResolutions": ["apology email"]
  },
  "decision": {
    "action": "offer coupon",
    "reason": "3rd delay + prior resolution was apology only → compensation escalation",
    "rejectedAlternatives": [
      { "action": "re-apology", "reason": "already tried" },
      { "action": "full refund", "reason": "cost excessive" }
    ]
  },
  "toolCalls": [
    { "name": "coupon-generator", "result": { "value": "10%", "expiry": "30d" } }
  ],
  "handoff": null,
  "guardrails": { "triggered": [], "passed": ["PII", "cost-cap"] }
}
```

```typescript
// OpenTelemetry span form
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("response-agent");
await tracer.startActiveSpan("response.generate", async (span) => {
  span.setAttribute("customer.category", input.category);
  span.setAttribute("decision.action", "offer coupon");
  span.setAttribute("decision.reason", reason);
  span.addEvent("alternatives-rejected", { count: 2 });
  // ...
  span.end();
});
```

## Antipatterns

**Customer support**: running without records makes "why was this customer issued a coupon" unanswerable. During audit you can only say "the agent decided autonomously," and you cannot compare decision patterns before vs after a prompt change — improvement collapses into trial and error.

**Finance / regulated systems**: when transaction-approval or credit-judgment agents are untraceable, regulator requests cannot be answered. Record input, applied rule, and rejected alternatives as spans, and retain them for at least the regulatory minimum (typically 5–7 years).

## Invocation example

```
"Apply Decision Traceability to Response Agent.
Record input context, chosen rationale, rejected alternatives, and handoff
as OpenTelemetry spans, and link the trace ID to the parent Intake Agent span."
```

## Related patterns

- Module Contract — what the records of compliance/violation refer to
- Evaluation and Guardrails — input data for evaluation