Trace a root cause

---
name: "aboutcodex-root-cause-trace"
description: "Trace a reproduced failure across data and control flow to the code or configuration that creates it. Use when the user has a reproducible defect and asks for the underlying cause."
---

# Trace a root cause

Trace a reproduced failure across data and control flow to the code or configuration that creates it.

## Workflow

1. Begin from the observed failure and follow the earliest incorrect value or decision backward.
2. Inspect callers, configuration, persistence, serialization, and boundaries that can transform the value.
3. Form competing hypotheses and falsify them with narrow observations or tests.
4. Identify the faulty assumption and explain why the visible symptom appears in this path.
5. Propose the smallest correction and the regression check that would fail before it.

Read `references/NOTES.md` before finalizing the work. Follow project instructions and the user's authorized scope. Use available evidence, label assumptions, and never report a check as passing unless it actually ran.

## Deliverable

An evidence-backed causal chain and a focused correction target. State material limitations and link to changed files or rendered evidence when available.