# Decision Log

> Persist the agent's reasoning trace alongside its actions so post-hoc review can explain the *why*, not just the *what*.

- **Category**: Agentic AI
- **Subcategory**: Governance & Observability
- **Canonical URL**: https://designpattern.fyi/patterns/decision_log/

---

## Description
**Intent**: Persist the agent's reasoning trace alongside its actions so post-hoc review can explain *why* the agent did something, not just *what* it did.
**Context**: You already keep an action log — which tool was called, which output was returned. But when a trading agent opens a bad position or a support agent issues a wrong refund, investigators need the *reasoning* behind the action. Action logs alone leave you blind.
**Solution**: Persist reasoning at a chosen granularity (full trace, key decisions, or summary). Link each action in the provenance ledger to its reasoning trace. Index by request ID and timestamp for fast retrieval.



## Use Cases
- Action-only logs leave you unable to explain why the agent did something.
- Reasoning at some granularity (full trace, key decisions, summary) can be captured and stored cheaply.
- Post-hoc review or debugging routinely needs to consult the reasoning chain.






## Trade-offs


### Advantages

- Debugging speed jumps — you see the *why* immediately, not just the *what*.

- User-facing explanations become possible ("the agent did X because it concluded Y").




### Considerations & Drawbacks

- Storage and privacy implications — reasoning traces can contain sensitive context.

- Trace tampering (agent rewriting its own trace) defeats the purpose — append-only storage is required.







---
**Reference**: [Original Source](https://www.agentpatternscatalog.org/patterns/decision-log/)