Run Trace

You append low-overhead, structured records per meaningful step — tool call, observation, reflection, error. Three surfaces: operational, cognitive, contextual. Never block execution to log.

Hard Rules

Append to .agent-loom/traces/<run-id>.jsonl — one JSON object per line per references/TRACE-SCHEMA.md. Reuse step_id from active structured-planning plan when present. Never persist secrets — refs only in input_ref / output_ref. Logging is append-only — never rewrite prior lines. Ensure .agent-loom/traces/ is gitignored in consumer projects.

---

Workflow

Step 1 — Allocate run_id

Format: YYYY-MM-DDTHH:MM:SSZ-<slug> at run start. Create empty jsonl file.

Step 2 — Append per step

After each meaningful event, append one record with correct surface:

Event	Surface
Tool/command executed	operational
Plan/route/reflection	cognitive
cwd, branch, versions	contextual

Step 3 — On error

Set error field on the operational record. Continue tracing if run continues.

Step 4 — Query when needed

python3 .agents/skills/run-trace/scripts/trace_query.py <path> timeline
python3 .agents/skills/run-trace/scripts/trace_query.py <path> errors

Step 5 — Hand off

On failed run, pass trace path to fault-localize.

---

Gotchas

• Pretty-printed JSON breaks JSONL — single-line objects only.
• Logging raw env vars may leak secrets — whitelist keys only.
• High-frequency polling loops — batch or sample; don't log every poll.

---

Output Format

## Run trace — [run_id]

Trace file: `.agent-loom/traces/[run_id].jsonl`
Records: N | Errors: N

Latest:
- [ts] [surface] [step_id] [action]

Query: trace_query.py [path] timeline

---

Examples

Teaser: 5-step plan run → 12 operational + 3 cognitive records → S3 error captured with exit code.

Full pairs: references/examples.md

---

Common Rationalizations

Excuse	Reality
"Tracing is too heavy"	One JSON line per step is cheap.
"I'll remember what happened"	You won't — especially after revert.
"Chat history is enough"	Not structured; can't query errors programmatically.
"Secrets in output are fine locally"	Traces get committed, shared, uploaded — refs only.
"Skip cognitive surface"	Route decisions are the hardest to debug.

Verification

• Trace file exists and is valid JSONL
• step_ids align with plan when planning active
• No secrets in trace payloads
• traces/ gitignored

Red Flags

• Trace file with invalid JSON lines
• Missing error field on failed tool steps
• Secrets written to jsonl

Prune Log

Last pruned: 2026-07-05

• Initial release from high-leverage skill spec (Skill 4 family)

Impact Report

Trace: [run_id] | Records: N | Errors: N | Path: .agent-loom/traces/...