Claude Skill

trace

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

LLM Mart · 0 points · 18 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download mirkobozzetto-arsenal-plugins_trace_skills_trace-ca70c8a.zip · 4 KB

mirkobozzetto/arsenal 15 1 forks MIT Updated 18d ago

Part of mirkobozzetto/arsenal — 7 skills

Install

skills CLI npx skills add https://github.com/mirkobozzetto/arsenal/tree/main/plugins/trace/skills/trace

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mirkobozzetto-arsenal@llmmart

Git git clone https://github.com/mirkobozzetto/arsenal.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mirkobozzetto/arsenal collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Trace

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.

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.

Execution policy

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.

Files (arsenal)

references

format.md 2.3 KB

# trace ledger format

## Location

`<project_root>/.claude/trace.md` - one per project. The hook also keeps
`<project_root>/.claude/.trace-state` (a JSON snapshot of the last working-tree
state) so it never logs the same change twice. Both live under `.claude/`, which
is why the hook excludes `.claude/` paths from its own detection: the ledger's
writes must not re-trigger it.

## Entry shape

One line per work block, newest at the bottom:

```
- [<context>] <iso-date> | done: <what> | files: <paths> | status: <s>
```

- `context` - `brief:<slug>` | `propose:<NNNN>` | `<top-dir>` | `chat`. Inferred from
  the changed paths (a change under `docs/brief/<slug>/` -> `brief:<slug>`, etc.).
- `what` - mechanical entries say `edited N files`; manual entries carry the
  intent the user gave, optionally prefixed with a stable id (`1.2`, `T03`).
- `files` - comma-separated paths, truncated with `+N more` past 8.
- `status` - `wip` | `in_progress` | `shipped`. The mechanical hook always writes
  `wip` (it cannot know intent). `shipped` is a claim of verified-done and only
  comes from a manual `/trace done ... --status shipped`.

## Mechanical vs intent

The Stop hook is deterministic and cheap: it logs the working-tree delta since
its last fire, every turn that changed files, with no model call. It captures
*what files moved*, never *why*.

The upgrade path (not built): a Stop hook that returns
`hookSpecificOutput.additionalContext` asking the model to write the entry,
capturing the *why* at the cost of tokens on every work-turn. Until then, the
*why* comes from `/trace done`.

Known ceiling: re-editing the same file across turns without changing its git
status code is not re-logged (the delta is empty). And a non-git project is not
observed at all - the hook exits silently.

## Relation to ship's trace.md

`ship` writes its own `trace.md` inside a run's output dir (for a brief, that is
the brief folder): a **per-run resume ledger**, the single source of truth to
resume one ship execution. This project-level `.claude/trace.md` is a different
thing: a **cross-session activity log** spanning every context, not tied to one
artifact. They share a name and a spirit (markdown, append, honest progress) but
not a scope. Kept separate on purpose; `next` reads both - the artifact statuses
for the board, this ledger for "what moved lately".

scripts
- trace.cjs 7.1 KB · in bundle

SKILL.md 1.1 KB

---
name: trace
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

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.

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.

## Execution policy

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.