| 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.
