tracedeck — structured decision logs for AI agents

The debugging fix for "the 200 status code that is completely wrong". Agents don't crash — they confidently execute the wrong plan. The only artifact is a 100k-token context window no human can audit. tracedeck replaces it with a git-like decision log: every decision point is a structured record written to a known directory by convention, replayable, diffable, and convertible into regression tests.

Why

• Traces alone are unreadable. A single turn is 3-15 LLM calls; a failed run at turn 40 is 80k+ tokens. Structured decision records — decision, rationale, sources, confidence, cost — turn debugging into "check the decision log", not "read the context window".
• Decision-point diffing barely exists. When you change a prompt or swap a model, you need to know which decision points changed and in what direction — the agent equivalent of a code diff.
• The eval-debugging loop is the discipline that scales. Every resolved failure becomes a test case; every test case that fails triggers an investigation. failures closes that loop automatically.

Record schema

One JSON object per line, runs/<run_id>.jsonl:

{"run_id": "r1", "step": 3, "decision": "use_get_pipeline_logs",
 "rationale": "deploy failure is in the pipeline, not the image",
 "sources": ["ops/run-4821.log"], "confidence": 0.91, "cost": 0.012,
 "tool_calls": [{"tool": "get_pipeline_run_logs"}], "status": "done",
 "model": "claude-sonnet", "timestamp": "2026-08-15T12:00:00+00:00"}

Required: run_id, step, decision. Optional: everything else.

Usage

./tracedeck init ~/traces

# agents append records (flags or --stdin for JSON)
./tracedeck record ~/traces --run-id r1 --step 1 --decision use_lookup \
    --rationale "well index docs exist" --sources '["pvt/black-oil.md"]' \
    --confidence 0.9 --cost 0.001
echo '{"run_id":"r1","step":2,"decision":"escalate","status":"failed"}' \
    | ./tracedeck record ~/traces --stdin

./tracedeck replay ~/traces r1          # git-log-style rendering
./tracedeck diff ~/traces r1 r2         # decision-point diff (exit 1 if differs)
./tracedeck golden ~/traces r1          # mark known-good run
./tracedeck check ~/traces r2           # regression detection vs golden
./tracedeck failures ~/traces r1        # extract failed steps -> eval test cases
./tracedeck runs ~/traces               # list runs + decision-point counts

diff/check exit non-zero on divergence, so CI can gate on agent regressions.