show-me-your-work

# Show me your work Delegation and optional capabilities follow `../poteto-mode/references/codex-agent-runtime.md`. 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 task history. 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 Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (the **unslop** skill applies to log text too). A reviewer should understand each row without decoding it. 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 compaction. A pickup or replacement agent starts a new run. When appending to an existing log, begin with a `start` row that names the prior timestamp range this run did not write and identifies this run in its evidence. After another run writes a `start` row, read the tail and add your own new `start` before continuing. Reserve `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 it only when the work is ambitious enough that a reviewer needs the trail to trust the result: a large cross-language port, a multi-week migration, anything where confidence has to be shown rather than assumed. A committed log renders as a table in the PR. ## 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 evidence produced by committed scripts over hand-made one-offs, so a reviewer can re-run it (the **encode-lessons-in-structure** principle skill). ## Audit the log against supported task history At the end of the run, check the log against the current task through supported task-history APIs. If that surface is unavailable, use the active conversation digest plus live git and artifact state. Do not scrape a private host store. Walk this run's rows against what happened. Each stretch starts at its `start` row, or the first row when this run created the log, and ends at another run's `start`: - Check that every row maps to a real decision or action. - Check that each row's evidence resolves and shows what the row claims. - A fork, pivot, or abandoned approach that shaped the work but isn't logged is a gap. Add it. - Add a superseding row for a claim or pointer that is wrong. Preserve the original row. Correct the log, not the story. The audit never edits or removes a row, even an invented one. When a row records neither a real decision nor a real action, or its claim or evidence is wrong, add a row that supersedes it with what actually happened and a pointer that resolves. This audit does not check rows outside this run's stretches. If this run's own work shows one of them is wrong, supersede it like any wrong call. ## Cross-model review of the trail Before handing back, request an independent review through an installed profile with a different observable model family when available. Otherwise use a generic independent agent and label the model pair inherited or unverified. If independent agents are unavailable, fail closed on claiming cross-model review and report that limitation. The reviewer reads the audit trail and supported task history or digest, then flags what the user should inspect. - Decisions logged with weak or absent evidence. - Verification steps skipped or claimed without proof in task history, receipts, or live state. - Choices that look risky in hindsight (premature, scope-creeping, papering over a symptom). - Gaps the user would otherwise miss on a casual skim. Every reply for a run that produced a trail ends with an "Attention" section. Lead with the reviewer's model on its own line (`reviewed by <model>`), then list each flag pointing to specific rows or moments. "No flags" is a valid value; the model name is not. The self-audit asks if the log told the truth; this asks what the user should still scrutinize even when it did. ## 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.