Skip to content

ykorovko/dotagents / skills/show-me-your-work

show-me-your-work

Verified

Keep a reviewable TSV decision trail for long-running or unattended work. Use only when the user explicitly asks for show-me-your-work or a decision log.

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

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: python3 <skill-directory>/scripts/log.py <logfile> <phase> <decision> <why> <evidence> <result>. Resolve <skill-directory> from the installed skill before running it. The helper 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. If Python 3 is unavailable, append the row with another local tool while preserving those safeguards.

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.

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.

If the consuming repository does not already ignore these paths, suggest adding decisions.tsv and .audit/ to its ignore file. Do not edit ignore rules unless the user has authorized repository changes.

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.

Audit the log against the transcript

At the end of the run, before handing back, check that the log tells the truth. Compare it with the current session context and the evidence produced during the work. If the harness exposes a clearly identified transcript for this session inside the active workspace, you may use it. Never search home directories or unrelated session histories for transcripts. If no transcript is available, audit against the context you can access and disclose that limitation. Walk the log against what actually happened:

  • Every row maps to a real action. Cut invented or aspirational entries.
  • 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.
  • Drop padding. If nobody would audit a row, it doesn't earn its place.

Fix the log, not the story. If the work diverged from what a row claims, the row is wrong.

Independent review of the trail

Before handing back, use an independent reviewer when the harness provides subagents and the user permits delegation. Prefer a different model family when one is available. The reviewer reads the audit trail and the accessible run context, then flags what the user should pay attention to. This is not a redo of the work, but a scan for what's suboptimal or risky. If independent review is unavailable, perform the same review yourself and say so.

  • Decisions logged with weak or absent evidence.
  • Verification steps skipped or claimed without proof in the transcript.
  • Choices that look risky in hindsight (premature, scope-creeping, papering over a symptom).
  • Gaps the user would otherwise miss on a casual skim.

Every final reply for a run that produced a trail ends with an "Attention" section. State whether it was independently reviewed and identify the reviewer when known, then list each flag pointing to specific rows or moments. "No flags" is valid. 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.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall