trace · diff
git:20260902.b370de6 to git:20260921.b4cdfe3
9 added, 11 removed. Audit A to A.
---
name: trace
- description: Show the provenance trace — every reported number linked to the SQL that produced it, with a confidence badge. Use after an analysis when someone asks "where did that number come from?"
+ description: Show the provenance trace, linking every reported number to the SQL that produced it with a confidence badge. Use after an analysis when someone asks "where did that number come from?"
---
- # /trace — expose the query logic behind every number
+ # /trace: expose the query logic behind every number
Renders one self-contained HTML that ties each reported number (a **finding**) back to the **query**
that produced it, labeled by confidence: **cited** (the agent named the query), **value-match** (a
query's captured `result_value` equals the number), or **inferred** (nearest query in time). Unmatched
- findings and orphan queries are shown, not hidden — an unverified number is the most important thing to
+ findings and orphan queries are shown, not hidden. An unverified number is the most important thing to
surface. This is the on-demand artifact for any "prove it" moment.
It reads the provenance infrastructure: the query log (hook-stamped with `analysis_id` +
`result_value`), the findings manifest, and the reconciler.
## Steps
1. **Resolve the analysis.** Read the current `analysis_id` and active dataset:
```bash
python3 -c "
import sys; sys.path.insert(0, '.')
from helpers.knowledge.analysis_context import current_analysis_id
from helpers.provenance.eval_driver import _active_dataset
print(current_analysis_id(create=False) or '', _active_dataset())
"
```
- If there is no current analysis, there is nothing to trace yet — say so and stop (or, for a past
+ If there is no current analysis, there is nothing to trace yet. Say so and stop (or, for a past
run, point `build_trace` at that analysis_id explicitly).
2. **Build + render the trace.** Date is today (`date '+%Y-%m-%d'`):
```bash
python3 -c "
import sys; sys.path.insert(0, '.')
from helpers.provenance.trace_viewer import build_trace
print(build_trace('<analysis_id>', '<dataset>', '<YYYY-MM-DD>'))
"
```
This reconciles (writes `working/provenance_<analysis_id>.json`) and renders
`working/trace_<analysis_id>.html`. Both are gitignored working files.
3. **Open it.** `open working/trace_<analysis_id>.html` (macOS). It's self-contained and
- projection-friendly — large type, collapsible SQL, colored confidence badges.
+ projection-friendly, with large type, collapsible SQL, and colored confidence badges.
4. **Read it out.** Walk the findings top to bottom: the number, its badge, the SQL. Call out anything
- **unmatched** (a number with no query behind it) — that's the honesty check, and the thing to fix.
+ **unmatched** (a number with no query behind it). That is the honesty check and the thing to fix.
## Notes
- - **Confidence is itself provenance.** A `value-match` is strong (the SQL actually returned that
- number); `inferred` is a hint, not proof — say so when reading it out.
- - **Captured fallback.** For a slide/recording where a live run isn't guaranteed, build the trace
- ahead of time and ship the HTML; the demo opens a real artifact instead of risking a live miss.
+ - **Confidence is itself provenance.** A `value-match` is strong because the SQL actually returned that
+ number. `inferred` is a hint, not proof, so say so when reading it out.
- **Teaching tie-in.** This is the concrete answer to "how do I know the agent didn't make the number
- up?" — pair it with the provenance-chain diagram.
+ up?" Pair it with the provenance-chain diagram.