---
title: "Decision Traceability"
description: "Record judgment rationale, choices, and collaboration paths as structured logs."
canonical: "https://architecture.reopt.ai/patterns/decision-traceability"
language: "en"
last-updated: "2026-10-20"
alternate-markdown: "https://architecture.reopt.ai/ko/patterns/decision-traceability.md"
site-index: "https://architecture.reopt.ai/llms.txt"
source: "reopt architecture"
---

# Decision Traceability

> Record judgment rationale, choices, and collaboration paths as structured logs.

- **Category:** Trust & Verification
- **OCLS phase:** SHARPEN
- **Slug:** `decision-traceability`

## Judgment question

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

## Context

As an agent system grows in complexity, you must be able to answer "why did this outcome happen." Evaluation, improvement, incident response, and audit all assume a decision record exists. Trying to govern without traceability is debugging without logs.

## Problem

Without decision records you cannot pinpoint which agent caused an incident or what rationale picked a given module. Evaluation criteria exist in a vacuum because there is no data to evaluate against, and the system becomes an unexplainable black box. In regulated contexts, the absence of an audit trail is itself a compliance violation.

## Forces

- Recording every decision raises storage and performance cost; recording selectively can drop critical rationale.
- Structured logs are easy to analyze but expensive to design; unstructured logs are immediate but hard to analyze later.
- Real-time tracing enables immediate response but loads the system; batch analysis is cheaper but slower on incident response.

## Solution

Equip every agent and module with structured decision logs. A log includes input context, chosen action with rationale, rejected alternatives, module called and its result, and handoff target with reason. Standardize log format as JSON or OpenTelemetry spans, and assign a trace ID that lets you follow causality across agents. Separate metrics that warrant real-time alerts (guardrail blocks, escalations) from metrics suited to batch analysis (quality distribution, cost trends).

## Application scenario

_Illustrative scenario — figures and company names in this page are hypothetical for explaining the pattern, not measured data._

In a customer-support system, the Response Agent offered a 10% coupon on a shipping-delay inquiry. Decision log: { traceId: 'tx-4521', agent: 'response', input: { category: 'shipping-delay', sentiment: 'frustrated', priorResolutions: ['apology email'] }, decision: 'offer coupon', reason: '3rd delay + prior resolution was apology only → compensation escalation', rejectedAlternatives: ['re-apology (already tried)', 'full refund (cost excessive)'], module: 'coupon-generator', result: { couponValue: '10%', expiry: '30d' } }. With this log, the QA Agent detected a coupon-overuse pattern and triggered a policy improvement: apology for the first three occurrences, coupon from the fourth.

## How it breaks

Without decision records, "why was this customer issued a coupon" is unanswerable. When coupon cost exceeds budget there is no data to analyze, and audit yields only "the agent decided autonomously." Prompt changes cannot be compared pre/post, so improvement collapses into trial and error.

## Implementation pattern bridge

- Structured Logging
- Distributed Tracing

Collects per-agent decision logs in structured form (JSON, OpenTelemetry spans) and implements tracing infrastructure that captures causal relationships.

## Related

- [Evaluation and Guardrails](https://architecture.reopt.ai/patterns/evaluation-and-guardrails.md)
- [Module Contract](https://architecture.reopt.ai/patterns/module-contract.md)

## References

- AI Governance by Design for Agentic Systems — Preprints.org
- Model AI Governance Framework for Agentic AI — IMDA (Singapore)

---

_Markdown representation of https://architecture.reopt.ai/patterns/decision-traceability. Full index: https://architecture.reopt.ai/llms.txt HTML original: https://architecture.reopt.ai/patterns/decision-traceability · 한국어: https://architecture.reopt.ai/ko/patterns/decision-traceability.md_