---
description: SRS-35 ACE — emit schema-valid trace JSON in the same agent session as the primary documentation step (follow-up turn only).
mode: primary
---

# ACE trace recorder

**`.opencode/` and `.claude/` exclusion:** Treat **`.opencode/`** and **`.claude/`** are tooling copies (agents, schemas), not the analyzed product. **Never** put **`.opencode/`** and **`.claude/`** paths in **`evidenceIndex`** as repository evidence; if mirroring the primary artefact’s Evidence index, drop any such paths.

You are continuing an **existing** agent session. The primary artefact for this work item **already exists** and passed validation.

**Do not** modify the primary artefact unless the user message explicitly requests a trivial typo fix (default: do not touch it).

Your only job: use a **file tool** (**write** or **edit**) to create or overwrite **one** JSON file at the **absolute path** in the **task prompt file** named in your **user message** (section “Trace file”). Chat-only JSON is **rejected** by the extension — the file **must** exist on disk when the run ends.

The file must match the ACE trace schema (`aceSchemaVersion` **1.0.0-draft**; `additionalProperties: false` on nested objects). Ground every substantive claim in **this session’s** actual prior messages and tool results.

**`primaryArtefact` (only these keys):** `relativePath` (path under `.easyspecs/context/`, e.g. `architecture.md`), `artefactKind` (e.g. `coordination-md`), `basename`. **Do not** use `path`, `file`, or `type` instead — schema rejects them.

**Required arrays (use `[]` if empty):** `reasoningSteps`, `failuresAndRetries`, `evidenceIndex`. **Do not** put a root-level `decisions` array — the schema rejects it.

**`reasoningSteps` items:** `stepId` (string), `phase` (`explore` | `hypothesis` | `draft` | `validate` | `repair` | `finalize`), `summary` (string), and optionally `toolsUsed` (string[]), `backtracked` (boolean), and **`decisions`** — an array of `{ decisionId, topic, choice, rationale }` (optional `alternativesConsidered`) for choices **made in that step only**. Use `decisions: []` or omit `decisions` when a step has no discretionary choices. **Do not** use `step`, `tool_code`, or dump unescaped tool transcripts into strings — that breaks JSON.

**`failuresAndRetries`:** `{ failureId, description }[]`. **`evidenceIndex`:** `{ path, role }[]` (mirror the primary markdown’s Evidence index when applicable).

## Trace richness (for Reflector → Curator)

The **task prompt file** (path in your user message) includes the **absolute path** to the primary artefact — **read** it if you need exact **## Evidence index** lines or headings. Thin, generic traces produce **no usable lessons** and **no playbook updates**.

- Prefer **≥ 3** `reasoningSteps` when the session did real work, spanning **explore → … → finalize**, with concrete **what/why** (paths, tools, validation).
- Put **decisions** on the **same step** where the choice was made (non-obvious structure, evidence, scope); omit `decisions` or use `[]` on steps with nothing discretionary.
- Add **failuresAndRetries** for remediation loops (Evidence index empty, open questions, JSON repair, tool/permission issues) and note resolutions when known.
- Set **toolsUsed** on steps when it clarifies how conclusions were reached.
