show-me-your-work
Use when the user invokes `show-me-your-work`, for long-running, autonomous, or multi-phase work, or for work a human will review after stepping away.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- kind
- dev
- name
- show-me-your-work
- role
- helper
- description
- Use when the user invokes `show-me-your-work`, for long-running, autonomous, or multi-phase work, or for work a human will review after stepping away.
02 资源文件 2
- 参考文档references/decision-log-template.tsv38 B
- 脚本scripts/log.sh2.9 KB
03 SKILL.md 正文
Show me your work
Read the agent runtime contract before using runtime tools, loading related skills, or delegating. Use only capabilities and model IDs verified in this session.
Keep one canonical log.
The format
A single TSV file, one row per decision. 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.
- 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, 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).
Use the helper 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. It answers in one JSON line, {"ok":true,"changes":[["append","<absolute logfile>"]]}; on a failure it exits non-zero, and the last stderr line is {"ok":false,"errors":[…]}. 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.
Where it lives
By default the log is a working artifact, not committed. Keep it at decisions.tsv in a mktemp -d folder outside the checkout, or at a path the repository ignores, so checks that refuse untracked files still run.
Commit it only when the work is ambitious enough that a reviewer needs the trail to trust the result.
Rules
- One row is one decision or checkpoint.
- 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 (poteto-mode's Encode Lessons in Structure principle).
Audit the log against the transcript
At the end of the run, before handing back, check the log told the truth. Discover this run's authorized history or export using the runtime contract. If it is unavailable, audit against visible tool evidence and artifacts and report the missing transcript as a coverage gap. 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.
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, spawn an independent agent with the Reviewer role. If no separate context is available, mark the independent review incomplete. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky.
- 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 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.
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.
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.
04 同仓库更多 Skills
writing-great-skills
Use when creating, modifying, evaluating a skill.
writing-for-agents
Use when creating, editing, or reviewing a skill, AGENTS.md, CLAUDE.md, or another document agents read.
why
Use for questions about design rationale, the history of regressions or incidents, or the evidence behind thresholds and tradeoffs. Use `how` for runtime behavior. Do not use for plain commit or date lookups.
verify-video-archive
Use when validating the macOS or Linux archive workflow reached by `just convert-video`, including real media, prerequisites, terminal progress, source safety, locking, and recovery.
verify-transcript
Use when validating transcript CLI behavior, locating its verification features, or running the paid YouTube end-to-end check.
verify-skills
Use when verifying `just compile-skills`, `just remote-skills`, `just install-skills`, or `just skills-discover` in the skills repository, such as after changing their scripts or adding, renaming, or moving a skill.