Skip to content

dvy1987/agent-loom / .agents/skills/run-trace

run-trace

Verified

Append structured execution traces across operational, cognitive, and contextual surfaces with minimal overhead. Load when inspecting agent runs, logging tool calls and observations, enabling post-run debugging, or pairing with structured-planning step IDs. Also triggers on "trace this run", "log execution", "agent observability", "run log", or when fault-localize needs evidence. Default-on during multi-step plans. Traces live at .agent-loom/traces/ — git-ignored by default.

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:

EventSurface
Tool/command executedoperational
Plan/route/reflectioncognitive
cwd, branch, versionscontextual

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

ExcuseReality
"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/...
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall