trace ยท diff
git:20260819.5b258e7 to git:20260905.c68a71a
16 added, 39 removed. Audit A to A.
---
name: trace
- description: Read or hand-write the project progress ledger (.claude/trace.md). Use when the user says "/trace", "what did I do", "log this", "trace done", or wants to record or review what moved this session. The automatic Stop hook already logs file changes; this skill is the reader and the manual writer for the intent the hook cannot infer.
- disable-model-invocation: true
- argument-hint: "[done <what> --files a,b --id N.x --status shipped] | (empty to read)"
- allowed-tools: Bash
+ description: Read or explicitly record project progress using the existing deterministic trace script.
+ argument-hint: "[done <what> --files a,b --id id --status shipped] [--read n]"
---
- # trace
-
- One ledger: `<project_root>/.claude/trace.md`. The Stop hook writes mechanical
- entries automatically (which files changed, each turn that touched files). This
- skill is the **reader** and the **manual writer** for the *why* the hook cannot
- infer. It never invents a second format - it shells out to the same script.
-
- ## Routing
-
- Let `S` = `${CLAUDE_PLUGIN_ROOT}/skills/trace/scripts/trace.cjs`. Run from the
- project root (so the ledger and git detection resolve to this repo).
-
- - **`/trace`** (no args) -> read recent entries:
- ```bash
- node "$S" --read 12
- ```
- Print the output as-is. Do not summarize unless asked.
+ # Trace
- - **`/trace done <what> [flags]`** -> write one clean entry:
- ```bash
- node "$S" done "<what>" [--files a,b] [--id N.x] [--status shipped|in_progress|wip] [--context brief:<slug>]
- ```
- Map the user's words to `<what>`. Pass `--files` when they name files,
- `--id` for a brief Unit (`N.x`) or propose task (`T0n`), `--status shipped` when the
- work is truly done and verified (default `wip`). Context is inferred from the
- files when omitted.
+ Use scripts/trace.cjs for reading or requested entries in .claude/trace.md.
+ No new format or LLM reviewer. The mechanical hook records file activity,
+ not successful delivery; never upgrade wip to shipped without evidence.
- - **Anything else after `/trace`** -> treat the free text as the `<what>` of a
- `done` entry, status `wip`, unless the user clearly meant to read.
+ Keep this cross-session activity log distinct from a ship run's task intent.
+ Do not copy every event between them. The runtime owns process/evidence state.
+ Only record a manual intent entry when asked. Read recent entries and stop;
+ do not reopen the work they describe.
- ## Notes
+ ## Execution policy
- - The hook covers automatic capture; only reach for `done` when the user wants
- to record intent ("note that I finished the auth refactor") that bare file
- paths do not convey.
- - `--status shipped` is a claim of verified-done, not attempted. Use the user's
- evidence, do not upgrade a `wip` to `shipped` on your own.
- - For the entry format and how this relates to ship's per-run `trace.md`, see
- [references/format.md](references/format.md).
+ Work solo. Ask before any subagent or reviewer, even in auto mode. Explain
+ the independent scope and expected benefit first. No hidden advisor, nested
+ delegation, model retuning, repeated successful checks, or progress spam.
+ Use existing context before asking questions. Stop when the requested result
+ is delivered. User stops and scope changes override pending steps.