trace-history

name	trace-history
description	Reads and filters production/traces/decision_ledger.jsonl to display a timeline of agent decisions. Supports filtering by agent, risk_tier, task_id, outcome, and date range.
argument-hint	[--agent <name>] [--risk High|Medium|Low] [--task <task_id>] [--outcome pass|fail|blocked] [--since YYYY-MM-DD] [--last <N>]
user-invocable	true
allowed-tools	Read, Bash
effort	1
when_to_use	Use to audit why a decision was made, debug a failed task, review high-risk choices, or produce a timeline of agent activity for a session or sprint.

Trace History

Read production/traces/decision_ledger.jsonl and display a filtered, human-readable timeline of agent decisions.

Execution

The rendering and filtering logic is implemented in scripts/trace-history.sh. This skill delegates to that script — do NOT re-implement parsing here.

1. Run the backing script

Invoke exactly once, passing $ARGUMENTS through unchanged:

bash scripts/trace-history.sh $ARGUMENTS

The script handles: flag parsing, filtering, rendering (pretty or JSON), empty-ledger short-circuit, and invalid-argument rejection. Return the script's stdout verbatim to the user.

2. Supported flags (all optional)

Flag	Default	Meaning
--agent <name>	all	Filter by agent_id
--risk <High|Medium|Low>	all	Filter by risk_tier
--task <id>	all	Substring match on task_id
--outcome <pass|fail|blocked|skipped>	all	Filter by outcome
--since <YYYY-MM-DD>	no limit	Only entries with ts >= date
--last <N>	20	Keep last N after other filters
--format <pretty|json>	pretty	Output format

3. Output format

Pretty (default): timeline with risk badges (🔴🟡🟢) and outcome emojis (✅❌⛔⏭️), grouped with separators and totals. Failed/blocked entries trigger a /resume-from hint automatically.

JSON: raw matching entries as a JSON array — use when piping to another tool.

4. Empty or no-match

The script emits 📭 messages for an empty ledger or zero-match filter. Return those messages as-is; do not fabricate data.

---

How decisions get into the ledger

Agents append one JSON line per significant decision to production/traces/decision_ledger.jsonl.

Append format:

{"ts":"2026-04-16T10:30:00Z","session":"main","agent_id":"backend-developer","task_id":"042","request":"Choose JWT signing algorithm","reasoning":"RS256 supports multi-service verification without sharing secrets","choice":"RS256 over HS256","outcome":"pass","risk_tier":"Medium","duration_s":18}

When to write a ledger entry (per coordination-rules.md Rule 15):

• Any decision with risk_tier Medium or High
• Any decision that was disputed or required fallback
• Any Circuit Breaker state transition (CLOSED → OPEN → HALF-OPEN)
• Any cross-agent handoff with a non-trivial acceptance criteria
• Task completion or failure (final outcome of a checkpoint)

Low-risk decisions (trivial style choices, obvious fixes) may be omitted to keep the ledger focused on decisions worth auditing.