Show me your work

For work a human reviews after the fact, a decision trail lets them reconstruct what was decided, why, and on what evidence, without rerunning the work or reading the whole transcript. Keep one canonical log so the trail is consistent and a future agent can find it.

The format

A single TSV file, one row per decision. TSV because GitHub renders it as a sortable table, column -s$'\t' -t and spreadsheets read it, and a row appends with one command. Cells stay single-line. Evidence is a pointer, not prose.

Copy references/decision-log-template.tsv (the header row) to start a clean log. Columns:

• ts. ISO8601 timestamp. The timeline axis.
• phase. The phase or workstream.
• decision. What was chosen or done, one line.
• why. The reason in plain words. If a principle drove it, say it plainly (explored options first, this was a one-way door), not as a jargon tag.
• evidence. A link or path that proves it: commit SHA, PR number, file:line, or an artifact, trace, or screenshot path. Never a paragraph.
• result. The outcome or predicate state: tests green, reverted, pixel-diff 0, INCONCLUSIVE, open.

An example, plain-spoken so a reviewer reads it at a glance. This is illustration only; don't copy these rows into a real log.

ts	phase	decision	why	evidence	result
2026-05-24T09:02:00Z	frame	counted the work first, about 100 components and roughly 75 hours	wanted to know the size before starting a long run	commit 3a9f1c2	found 5 things to sort out before starting
2026-05-24T09:40:00Z	harness	took screenshots of the old version before changing anything	so we can compare old against new and catch any visual change	scripts/snapshot.sh, baseline/	saved 120 reference screenshots
2026-05-24T11:15:00Z	widget	moved the widget styles over without changing how it looks	keep the change small and the result identical	commit 7c21e0a, pixel-diff 0	looks identical, tests pass
2026-05-24T12:30:00Z	widget	threw out a helper's work because its screenshots were blank	checked the real files instead of trusting its summary	worktree reset	reverted, tightened the instructions for next time

Logging a row

Use plain words and concrete actions in each entry.

Use the helper so rows stay well-formed: scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>. It stamps ts, writes the header on first use, strips stray tabs/newlines, and prefixes any cell starting with =, +, -, or @ with a single quote so a reviewer opening the log in a spreadsheet doesn't trigger formula execution. A bare printf appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.

Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. Skip the trivial and self-evident.

A run is one agent conversation, including later turns and summaries. A replacement agent or new conversation starts a new run. When appending to an existing log, begin with phase start. Add another start row when resuming after another run has written its own start row. Read the latest rows before resuming. Each start row identifies the timestamp range of preceding rows this run did not write, and its evidence identifies the current run. Reserve phase start for these boundaries.

Where it lives

By default the log is a working artifact, not committed. Keep it at decisions.tsv in the work dir, or .audit/<task-slug>.tsv when several efforts run at once, and leave it out of git. Most work doesn't need a committed trail; the local log still keeps the run honest and can be discarded after.

Commit the log only when the user authorizes a commit that includes it.

Rules

• One row is one decision or checkpoint. If it doesn't fit on one line, the decision isn't crisp yet.
• Append-only. A wrong call gets a new row that supersedes it. Never edit or delete history.
• Prefer reproducible evidence from available checks and artifacts.

Check the evidence

Before delivery, compare the log with available results and artifacts from this task. Use the start rows to identify this run's stretches. Audit those stretches rather than claiming to have verified another run's work. If current evidence disproves an earlier run's claim, append a correction that identifies and supersedes that row. Use a task transcript only when its location is supplied and access is permitted. Do not search unrelated private conversations.

• Check that each row describes a real decision or action.
• Check that each evidence pointer resolves and supports its claim.
• Add omitted decisions that materially affected the result.
• Correct inaccurate rows with a new row that identifies and supersedes the original.
• Mark unsupported results as unverified rather than invent evidence.

A decision trail alone does not require an independent code review or a second model. Use independent review when the user requests it or an applicable acceptance requirement mandates it. Report the log location and material evidence gaps at completion.

Reviewing the trail

Read top to bottom, follow the evidence pointers, spot-check. GitHub renders a committed TSV as a table; column -s$'\t' -t decisions.tsv renders it in a terminal. A row whose evidence doesn't resolve, or whose result is unverified, is the audit catching a gap.

Composing this skill

Other skills route their audit trail here instead of inventing one. Reference it by name and let it own the format; don't restate the columns.