reasoning-trace-recorder · diff
git:20260515.6be9f59 to git:20260812.7cc066c
8 added, 63 removed. Audit A to A.
---
name: reasoning-trace-recorder
description: "Auto-invokes for every Claude turn during active T4 task execution. Emits append-only trace events (file_read, output_claim, tool_call, decision) to .claude/plans/traces/{TASK_ID}.jsonl. Source of grounding-discipline checks. Disable: AF_TRACE_DISABLED=true."
when_to_use: "Every Claude turn during active T4 execution; silent if no .claude/plans/active.json or no active.task or AF_TRACE_DISABLED=true"
autoInvoke: true
allowed-tools: Read, Bash
effort: low
user-invocable: false
---
- > **AI-consumed reference.** Optimized for Claude to read during execution.
- > Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)
- > or [docs/getting-started/](../../../docs/getting-started/) depending on topic.
-
-
# Reasoning Trace Recorder
- **STATUS — v3.7.0-alpha.2 (Milestone B).** Forensic reproducibility per spec goal §2.1.3.
+ Forensic reproducibility. Append-only; never calls an LLM, never edits plan files or prunes traces.
## Behavior
- 1. Detect: if `.claude/plans/active.json` does NOT exist → exit silently
- 2. Read `.claude/plans/active.json` — if `active.task` is null → exit silently
- 3. For every emitted event from companion hooks/tools, append a line to `.claude/plans/traces/{TASK_ID}.jsonl`
-
- ## Event schema (one JSON per line)
-
- ```json
- {
- "ts": "2026-04-29T14:32:01Z",
- "event_id": "TR-00101-007",
- "task_id": "TASK-00101",
- "type": "output_claim",
- "payload": {
- "claim": "src/auth/jwt.ts exports verifyToken",
- "grounded": true,
- "grounded_by": ["TR-00101-003"]
- }
- }
- ```
+ 1. **Detect:** no `.claude/plans/active.json`, or `active.task` null, or `AF_TRACE_DISABLED=true` → exit silently
+ 2. **Append** one JSON line per emitted event to `.claude/plans/traces/{TASK_ID}.jsonl` (one file per T4 task)
## Event types
- | Type | Emitted by | Required payload fields |
- |------|-----------|-------------------------|
- | `file_read` | Read tool / hook | `path`, `lines_read`, `sha256` |
- | `output_claim` | Claude reasoning | `claim`, `grounded` (bool), `grounded_by` (array of event_ids) |
- | `tool_call` | PreToolUse hook | `tool_name`, `args_hash` |
- | `tool_result` | PostToolUse hook | `tool_name`, `exit_code`, `result_hash`, `duration_ms` |
- | `decision` | master-planner | `decision`, `reasoning`, `confidence` |
- | `phase_transition` | run-orchestrator | `from_phase`, `to_phase`, `gate_passed` |
-
- ## Grounding rule (per spec §11.1)
-
- An `output_claim` is **grounded** when ≥1 prior `file_read` event in the same trace covers the file/function/symbol named in the claim.
-
- If `grounded: false`, it is **flagged as potential hallucination** and surfaced via `/aura-frog:trace --hallucinations`.
-
- ## What this skill does NOT do
-
- - Does NOT call an LLM
- - Does NOT modify plan files (trace is independent of plan)
- - Does NOT enforce grounding (that's grounding-discipline rule's job — this just records)
- - Does NOT prune traces (retention is /aura-frog:plan-archive's responsibility)
-
- ## File location
-
- ```
- .claude/plans/traces/{TASK_ID}.jsonl
- ```
-
- One file per T4 task. Append-only; never edited or deleted by this skill.
+ `file_read` · `output_claim` (with `grounded: bool` + `grounded_by`) · `tool_call` · `tool_result` · `decision` · `phase_transition`.
- ## Storage budget
+ **Grounding rule (spec §11.1):** an `output_claim` is grounded when ≥1 prior `file_read` in the same trace covers the named file/function/symbol. Ungrounded claims are flagged and surfaced via `/aura-frog:trace --hallucinations`.
- Per task target: ≤500 events (typical task: 50-100 events). If a task exceeds 1000 events, post-execute-update-node hook flags `event: trace_overflow` and surfaces in /aura-frog:trace.
+ ## Budget
- ## Tie-Ins
+ ≤500 events per task target; >1000 events → `trace_overflow` flag via post-execute-update-node hook.
- - **Spec:** §9.5, §11.1 (grounding-discipline)
- - **Companion hook:** `hooks/tool-call-tracer.cjs` — emits tool_call/tool_result events
- - **Companion hook:** `hooks/tdd-red-failure-tracker.cjs` — emits decision events for RED phase
- - **Command:** `commands/trace.md` — reads traces for /aura-frog:trace output
- - **Rule:** `rules/core/grounding-discipline.md` — defines grounded:bool semantics
- - **Skill:** `failure-classifier` — reads recent trace events to score F2/F3
+ **Detail (JSON schema, per-type payload fields, tie-ins):** `skills/reasoning-trace-recorder/reference.md` — load on demand only.