show-me-your-work

把决策轨迹留下来

Keep one canonical log.

只保留一份规范日志。

The format

格式

A single TSV file, one row per decision. Cells stay single-line. Evidence is a pointer, not prose.

单个 TSV 文件，每决策一行。单元格保持单行。证据是指针，不是散文。

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

复制 references/decision-log-template.tsv（表头行）开始干净日志。列：

• 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.

• ts。 ISO8601 时间戳。

• phase。 阶段或工作流。

• decision。 选了或做了什么，一行。

• why。 白话理由。若原则驱动，说人话，别当术语标签。

• evidence。 证明它的链接或路径：commit SHA、PR 号、file:line，或产物/追踪/截图路径。绝不要一段话。

• result。 结果或谓词状态：tests green、reverted、pixel-diff 0、INCONCLUSIVE、open。

An example, plain-spoken so a reviewer reads it at a glance.

示例，白话，让审阅者一眼读懂。

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).

每条像跟同事说你干了啥。白话、具体动作，不要 AI 腔或抽象术语（日志文本也走 unslop）。

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. A bare printf appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.

用 helper scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>。它盖 ts、首次写表头、剥掉多余 tab/换行，并对以 =、+、-、@ 开头的单元格加单引号前缀。裸 printf 追加一行也行，但单元格来自生成或用户文本时留意同样字节。

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.

默认日志是工作产物，不 commit。放工作目录的 decisions.tsv，或多努力并行时用 .audit/<task-slug>.tsv，别进 git。

Commit it only when the work is ambitious enough that a reviewer needs the trail to trust the result.

只有活够野心、审阅者需要轨迹才信结果时才 commit。

Rules

规则

• 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 (the encode-lessons-in-structure principle skill).

• 只追加。错误决定用新行覆盖。绝不改或删历史。

• 优先用已 commit 脚本产出的证据，而非手搓一次性（encode-lessons-in-structure）。

Audit the log against the transcript

对照 transcript 审计日志

At the end of the run, before handing back, check the log told the truth. Read this run’s transcript under the active workspace’s agent-transcripts/ directory (the system prompt names the path). Don’t glob across ~/.cursor/projects/*/. That reads unrelated private chats. Walk the log against what actually happened:

跑结束交回前，检查日志说了真话。读本跑在当前工作区 agent-transcripts/ 下的 transcript（system prompt 点名路径）。别跨 ~/.cursor/projects/*/ glob——会读无关私聊。对照实际发生走读日志：

• 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.

修日志，别修故事。工作与行声称的分叉了，错的是行。

Cross-model review of the trail

跨模型审轨迹

Before handing back, spawn a subagent on a different model family from the one that did the work. 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.

交回前，在与干活不同模型族上 spawn subagent。自审不能替代。subagent 读审计轨迹与本跑 transcript，标出用户该注意什么。不是重做活，是扫次优或有风险处。

• 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.

• 证据弱或缺失的已记决策。

• 跳过或在 transcript 无证明却声称的验证步骤。

• 事后看有风险的选择（过早、范围蔓延、糊症状）。

• 用户随便扫会漏的缺口。

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.

产出轨迹的跑，每次回复以 “Attention” 小节结尾。先单独一行审阅者模型（reviewed by <model>），再列每条指向具体行或时刻的 flag。“No flags” 是合法值。模型名不是。

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.

从上到下读，跟证据指针，抽查。GitHub 把已 commit 的 TSV 渲成表。终端用 column -s$'\t' -t decisions.tsv。

Composing this skill

组合本 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.

其他 skill 把审计轨迹路由到这里，别自造一份。按名引用，让它拥有格式。别复述列。