work-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write the work report,

WORK-REPORT.md

at the working tree root: what the diff cannot show, for a reviewer or fresh session. One per tree, overwritten each run, so it reads as current state. Any directory (git or not, worktree or not), any shape of work (commits, loose edits, cross-repo changes, editor settings).

Follow the steps in order. Stop only on an unwritable path; missing

git

, no repo, or a quiet session still get a valid report.

在 working tree 根目录写入工作报告

WORK-REPORT.md

：记录 diff 无法展示的内容，供审阅者或全新会话阅读。每个工作树一份，每次运行都会覆盖，因此它呈现的是当前状态。支持任何目录（无论是否使用 git、是否为 worktree），也支持任何形式的工作（commits、松散编辑、跨仓库变更、编辑器设置）。

按以下步骤依次执行。只有路径不可写时才停止；缺少

git

、没有仓库，或没有实质操作的会话，仍应生成有效报告。

Never write without being asked

未经要求，绝不写入

Self-activated (user signalled work finished without naming the report): offer in one sentence, wait for a go-ahead. You may read the existing report first so the offer carries the Step 2 question. An explicit invocation (

/work-report

, "write the work report") is the go-ahead.

自行触发（用户表示工作已完成，但未明确提及报告）：用一句话提出此建议，并等待用户同意。你可以先读取现有报告，以便在提议中包含第 2 步的问题。明确调用（

/work-report

，“write the work report”）视为用户已同意。

Scope of "the work" = this chat session

“工作”的范围 = 当前聊天会话

Report what you did this session. Never infer it from

git diff

git log

: git already records that, and reconstruction loses the intent. A free-text note passed with the invocation sets emphasis (that topic leads each section), never narrows scope.

报告你在本次会话中所做的工作。绝不要根据

git diff

或

git log

推断：git 已经记录了这些内容，而事后重构会丢失意图。调用时传入的纯文本备注用于设定重点（该主题在各章节中居于首位），但绝不缩小范围。

Altitude - keep every entry the same size

信息粒度——保持每个条目大小一致

Goal and nested bullets: 1-2 sentences. List items: one sentence plus optional parenthetical. No paragraphs; the reader scans.

目标和嵌套项目符号：1-2 句话。列表项：一句，另可附括号说明。不要写段落；读者会快速扫读。

Step 1 - Locate the report

第 1 步 - 定位报告

<root>/WORK-REPORT.md

, root from

git rev-parse --show-toplevel

; outside git, the current directory.

<root>/WORK-REPORT.md

，根目录通过

git rev-parse --show-toplevel

获取；在 git 之外，则为当前目录。

Step 2 - Read the existing report and build on it

第 2 步 - 读取现有报告并在其基础上继续

An existing report (maybe another agent's) may belong to other work. Ask the user when its Goal is clearly unrelated to this session, or when both its session id and branch differ from the current ones. A matching session id waives the branch test: one session may build variants on several branches. A foreign report is often a deliberate handoff, so name what a fresh start drops: "WORK-REPORT.md may belong to other work (Add retry to CSV export, branch

feat/export-retry

). Extend it, or start a new report and drop its 2 open follow-ups and 1

[ignored]

entry?" Self-activated: fold this into the one-sentence offer. On "start new", write from this session alone; skip the rest of this step.

Otherwise extend, never regenerate: carry Problem → Solution and Abandoned entries with tags unchanged, widen the Goal if this session did, and disposition every carried follow-up (dropping keeps the report bounded across resumed sessions):

Carried follow-up	Where it goes
Done, after a changed course, a fork taken, or a check the diff cannot show (pipeline run inspected, email sent, console flag toggled)	Problem → Solution
Done, what it took recoverable from the diff	dropped, no trace
Rejected after evaluation	Abandoned, tagged `[considered]`
Dismissed by the user, or by a rule the user set (Step 4, Abandoned)	Abandoned, tagged `[ignored]`
Still open	kept verbatim
Obsolete, goal moved	dropped, no trace

现有报告（可能属于另一个 Agent）可能对应其他工作。如果其 Goal 与本次会话明显无关，或其 session id 与 branch 都不同于当前值，就询问用户。session id 匹配即可免除 branch 检查，因为一次会话可能在多个 branch 上构建变体。外部报告通常是有意交接的结果，因此要明确说明新开报告会丢失什么：“WORK-REPORT.md 可能属于其他工作（为 CSV 导出添加重试，branch

feat/export-retry

）。要扩展它，还是新建一份报告，并丢弃其中 2 个未完成的 follow-up 和 1 个

[ignored]

条目？”

自行触发时：将这个问题纳入那句话提议中。用户选择“start new”后，仅根据本次会话编写，并跳过本步骤的其余部分。

否则应扩展现有报告，绝不重新生成：原样保留 Problem → Solution 和 Abandoned 条目及其标签；如果本次会话扩展了目标，则扩大 Goal；并处置每一个继承的 follow-up（删除已关闭项，可以让报告在多次续接会话之间保持精简）：

继承的 follow-up	去向
已完成，期间改变过方案、选择过一条分叉路径，或执行了 diff 无法体现的检查（检查过 pipeline run、发送过 email、切换过 console flag）	Problem → Solution
已完成，且完成所需信息可从 diff 恢复	删除，不留痕迹
评估后否决	Abandoned，标记为 `[considered]`
用户或用户设定的规则（第 4 步，Abandoned）予以驳回	Abandoned，标记为 `[ignored]`
仍未完成	原样保留
已过时，目标已经变化	删除，不留痕迹

Step 3 - Offer the gitignore entry (first run in a repo only)

第 3 步 - 提供

.gitignore

条目（仅仓库中的首次运行）

Skip outside git, or when Step 2 found a report (the first-run test; stops re-asking after a decline). Otherwise run

grep -qxF '/WORK-REPORT.md' <root>/.gitignore

with the Step 1 root. Present: say nothing. Absent: say the report is a local artifact normally kept out of the branch diff, ask to add it, continue to Step 4 either way. On yes, append to

<root>/.gitignore

(trailing newline first if missing):

text

undefined

如果不在 git 中，或第 2 步找到了报告，则跳过（这是首次运行判定；用户拒绝后不再重复询问）。否则，以第 1 步确定的根目录运行

grep -qxF '/WORK-REPORT.md' <root>/.gitignore

。若已存在该条目：不作任何说明。若不存在：说明报告是本地产物，通常应排除在 branch diff 之外，询问是否添加；无论结果如何都继续第 4 步。用户同意后，追加到

<root>/.gitignore

（若缺少末尾换行，先补一个）：

text

undefined

Work report (work-report skill) - git add -f to commit it

/WORK-REPORT.md


Keep the leading slash: it anchors to the tree root, so a same-named file deeper down is not ignored, and still covers
every worktree.

/WORK-REPORT.md


必须保留前导斜杠：它将路径锚定到工作树根目录，因此更深层目录中的同名文件不会被忽略，并且仍可覆盖每个 worktree。

Step 4 - Compose the report

第 4 步 - 编写报告

Only what the diff cannot show: intent, reasoning, verification, next steps. Never restate commits or changed files. Reference artifacts (PR/issue URLs, file paths, ADRs), never paste them. Never reproduce the value of an API key, password, token, credential, or PII; note only that it exists and where (other agents read the report; it may be committed).

Header - exactly

# Work report

, then two identifier lines, one fact each, never merged. branch = where the work started: current branch on a new report, carried unchanged when extending. session id = last writer. Readers grep these lines and their fallback values:

text

undefined

只记录 diff 无法展示的内容：意图、推理、验证和后续步骤。绝不重述 commits 或变更过的文件。只引用 artifacts（PR/issue URL、文件路径、ADR），不要粘贴它们。绝不复现 API key、password、token、credential 或 PII 的值；只注明它们的存在及位置（其他 Agent 会读取此报告；它可能会被提交）。

Header - 必须严格为

# Work report

，然后写两行标识信息，每行只包含一个事实，绝不合并。branch = 工作开始时所在的分支：新建报告时使用当前 branch，扩展报告时原样沿用。session id = 最后一次写入者。读者会 grep 这些行及其回退值：

text

undefined

Work report

branch: <on a new report git branch --show-current,
```
(detached)
```
on a detached head,
```
(no git)
```
outside a repo or with git unavailable>
session id: <printenv CLAUDE_CODE_SESSION_ID, or
```
unknown
```
if unset>


Then five `##` headings, in order, each always present, `- none` under an empty one:

- **Goal** - what this work set out to do.
- **Problem → Solution** - numbered list. Entry when: a first attempt failed and you changed course; you took a real
  fork (≥2 viable options); or a follow-up the report already listed was finished (by anyone, this session included)
  and closing it is not recoverable from the diff or was itself a fork. Record problem and working approach, or fork
  and why. A finished follow-up failing this test just leaves *Follow-ups*. Fold verification the diff, PR and CI
  cannot show (retry path clicked through with the proxy down, a pipeline run inspected) into the **Solution** it
  verifies; when the verified work has no entry, the check is its own entry (**Problem** = what needed proving,
  **Solution** = the check and its result). A green test run is not an entry. Each changed course is its own entry,
  even inside a larger fix, and the failed attempt also goes to *Abandoned* as `[tried]`. Entry shape:

  ```text
  1.
      - **Problem:** description
      - **Solution:** description

Follow-ups - flat list of what the next session or reviewer picks up, each tagged:
- ```
[question]
```
  - unresolved decision or unknown, phrased as a question.
- ```
[action]
```
  - concrete work, imperative. Believed working but never exercised =
```
[action]
```
  naming the settling check. Valid with no owner.
Never here:
- Gap already decided against (accepted risk, platform out of scope): Abandoned
```
[considered]
```
  , or
```
[ignored]
```
  if the user, or a rule the user set, dismissed it.
- Shipping (commit, push, PR, merge, tag, release): the user's move, even if the session ends uncommitted.
- Invoking a skill or slash-command: state the outcome (
```
[action] Add regression tests for the retry path
```
  ), never the tool (
```
[action] Run /test-writer
```
  ).
Suggested skills - means for an outcome-only follow-up. List a skill only if it advances an
```
[action]
```
item, as
```
/skill - which follow-up it advances
```
.
Abandoned - what the next agent should not re-walk: dropped approaches, and carried follow-ups later rejected. Numbered, one sentence plus reason:
text
```
1. [tried] implemented or attempted, then reverted - why it was backed out
2. [considered] evaluated and rejected without building it - why it was rejected
3. [ignored] dismissed by the user or a rule the user set - the user's reason, "user's call", or the rule and its source
```
```
[ignored]
```
= user veto: later runs never re-raise, re-tag or re-offer it, except as the reopen check below. It needs the user's authority, given one of three ways:
- Directly: an explicit dismissal this session ("ignore that", "skip the Safari case", "don't bother").
- Through a rule the user stated or confirmed this session (a review bar such as "fix blockers only"), or one written in the repo's instruction files (AGENTS.md, CONTRIBUTING.md), applied to the item. Cite the rule and its source:
```
- non-blocker under user's bar "blockers only" (this session)
```
  , or the file path. One entry per item.
- Carried from the existing report.
A rule you cannot cite, a skill's default the user never confirmed, or your own rejection is
```
[considered]
```
with your reason. Silence, an unanswered
```
[question]
```
, or a deferral ("not now", "later") keeps it in Follow-ups; a deferral a ticket or doc already records gets no entry. Never invent the user's reason or rule.
The user lifts
```
[ignored]
```
by asking for that work again, or by changing or withdrawing the rule, which lifts every entry citing it. Reopen check: when a defect or failure this session shares a root cause or failing scenario with an
```
[ignored]
```
entry, keep the entry and add
```
[question] Does <defect> reopen [ignored] <item>?
```
. The user decides.

Example:

markdown

undefined

branch: <on a new report git branch --show-current,
```
(detached)
```
on a detached head,
```
(no git)
```
outside a repo or with git unavailable>
session id: <printenv CLAUDE_CODE_SESSION_ID, or
```
unknown
```
if unset>


接着按顺序给出五个 `##` 标题；每个标题都必须存在。如果某标题下没有内容，则写 `- none`：

- **Goal** - 本项工作旨在实现什么。
- **Problem → Solution** - 使用编号列表。以下情况应添加条目：首次尝试失败后改变方案；真正走向一个分叉（≥2 个可行选项）；或者报告已有的 follow-up 已完成（无论由谁完成，包括本次会话），且其关闭过程无法从 diff 恢复，或者关闭过程本身构成一次分叉。记录问题与有效方案，或分叉及其原因。已完成的 follow-up 如果不满足此测试，就仍然留在 *Follow-ups*。将 diff、PR 和 CI 无法体现的验证（代理中断时逐步验证重试路径、检查过 pipeline run）并入它所验证的 **Solution**；如果被验证的工作没有对应条目，则让该检查单独构成一个条目（**Problem** = 需要证明什么，**Solution** = 检查及结果）。测试运行全绿不构成条目。每次改变方案都要单独列为一个条目，即使它属于更大修复的一部分；失败尝试也要作为 `[tried]` 写入 *Abandoned*。条目格式：

  ```text
  1.
      - **Problem:** description
      - **Solution:** description

Follow-ups - 使用扁平列表，列出下一会话或审阅者要接手的事项；每项都要带标签：
- ```
[question]
```
  - 尚未解决的决策或未知事项，以问题形式表述。
- ```
[action]
```
  - 具体工作，使用祈使语气。认为方案可行但从未实际验证时，使用
```
[action]
```
  ，并写明用于最终确认的检查。可以没有负责人。
以下内容绝不能放在此处：
- 已经决定不予处理的缺口（已接受风险、平台不在范围内）：放入 Abandoned 并标为
```
[considered]
```
  ；若用户或用户设定的规则已驳回，则标为
```
[ignored]
```
  。
- 交付发布类操作（commit、push、PR、merge、tag、release）：这是用户要做的操作，即使会话结束时尚未 commit。
- 调用某个 skill 或 slash-command：说明结果（
```
[action] Add regression tests for the retry path
```
  ），绝不要写工具本身（
```
[action] Run /test-writer
```
  ）。
Suggested skills - 为仅需产出结果的 follow-up 提供实现手段。只有当某个 skill 能推进一项
```
[action]
```
条目时才列出，格式为
```
/skill - which follow-up it advances
```
。
Abandoned - 记录下一位 Agent 不应重新尝试的内容：已放弃的方案，以及后来被否决的继承 follow-up。使用编号列表，每项一句话并说明原因：
text
```
1. [tried] implemented or attempted, then reverted - why it was backed out
2. [considered] evaluated and rejected without building it - why it was rejected
3. [ignored] dismissed by the user or a rule the user set - the user's reason, "user's call", or the rule and its source
```
```
[ignored]
```
表示用户否决：后续运行不得再次提出、重新标记或重新提供该事项，例如下面的 reopen 检查。它必须由用户通过以下三种方式之一赋予权威：
- 直接给出：本次会话中的明确驳回（“ignore that”“skip the Safari case”“don't bother”）。
- 通过用户本次会话陈述或确认的规则（例如“fix blockers only”这样的审阅标准），或 repo 指令文件（AGENTS.md、CONTRIBUTING.md）中写明并适用于该事项的规则。引用该规则及其来源：
```
- non-blocker under user's bar "blockers only" (this session)
```
  ，或文件路径。每项只写一个条目。
- 从现有报告继承。
无法指出出处的规则、用户从未确认过的 skill 默认行为，或你自己的否决，都应标为
```
[considered]
```
并附上你的理由。保持沉默、未得到回答的
```
[question]
```
，或暂缓处理（“现在不做”“以后再说”），会让事项继续留在 Follow-ups；如果 ticket 或文档已经记录了暂缓决定，则不添加条目。绝不要编造用户的理由或规则。
用户要求再次处理该工作，或更改/撤销规则，即解除
```
[ignored]
```
；更改或撤销规则也会同时解除所有引用该规则的条目。reopen 检查：如果本次会话中的 defect 或 failure 与某个
```
[ignored]
```
条目具有相同根因或失败场景，则保留该条目，并添加
```
[question] Does <defect> reopen [ignored] <item>?
```
。由用户决定。

示例：

markdown

undefined

Work report

branch: feat/export-retry
session id: 3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d7a10

branch: feat/export-retry
session id: 3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d7a10

Goal

Make the CSV export survive a dropped connection by retrying failed chunk uploads.

Problem → Solution

- Problem: Retrying the whole export duplicated rows already written.
- Solution: Retry per chunk with an idempotency key; verified by killing the proxy mid-export and diffing the output.

- Problem: Retrying the whole export duplicated rows already written.
- Solution: Retry per chunk with an idempotency key; verified by killing the proxy mid-export and diffing the output.

Follow-ups

[question] Should the retry limit be configurable per tenant?
[action] Add regression tests for the chunk retry path.

[question] Should the retry limit be configurable per tenant?
[action] Add regression tests for the chunk retry path.

Suggested skills

/test-writer - Add regression tests for the chunk retry path.

/test-writer - Add regression tests for the chunk retry path.

Abandoned

[tried] Exponential backoff in the HTTP client - it retried non-idempotent POSTs elsewhere in the app.
[considered] Streaming the export over websockets - too large a change for the bug.
[ignored] Safari download filename encoding - user's call.

undefined

[tried] Exponential backoff in the HTTP client - it retried non-idempotent POSTs elsewhere in the app.
[considered] Streaming the export over websockets - too large a change for the bug.
[ignored] Safari download filename encoding - user's call.

undefined

Step 5 - Write the file and report back

第 5 步 - 写入文件并回复

Write

<root>/WORK-REPORT.md

, reply with the path and a one-line summary, naming any reopen

[question]

. If gitignored (Step 3), note a reviewer on the PR needs a deliberate

git add -f WORK-REPORT.md

写入

<root>/WORK-REPORT.md

，回复文件路径和一行摘要，并明确指出任何 reopen

[question]

。如果该文件已被 gitignore（第 3 步），说明 PR 上的审阅者需要有意执行

git add -f WORK-REPORT.md

。