Back to Details

completion-report

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Completion Report

完成报告

Produce the report that preserves the most material state in the least text.
Two rules generate everything else:
No material fact may be lost merely because the answer must be concise.
No execution detail survives merely because it happened.
生成能以最少文字保留最多关键状态的报告。
以下两条规则衍生出所有其他要求：
不得仅因需精简回答而丢失任何关键事实。
不得仅因某执行细节发生过就保留该细节。

Boundary

适用边界

This skill only communicates. It does not plan, replan, execute, verify, or repair. If work can still continue, control belongs to 
execute-plan
or 
plan-from-spec
— not here.
It also does not invent evidence. If something was not verified, the report says so.
此Skill仅用于沟通。它不负责规划、重新规划、执行、验证或修复。如果工作仍可继续，控制权属于
execute-plan
或
plan-from-spec
，而非此Skill。
它也不会编造证据。若某事项未经过验证，报告需如实说明。

Inputs

输入信息

From 
spec-interview/<slug>/
:
  • the contract — 
    SPEC.md
    when it exists; otherwise 
    PLAN.md
    , whose 
    Goal
    and the union of its 
    Done when
    conditions are the contract;
  • LEDGER.md
     — the record of what became true, with each entry's 
    Covers
    , evidence, and verification label;
  • PLAN.md
     — for the goal statement and any task that never produced a ledger entry.
Without a ledger, reconstruct the material facts from the run before reporting — but say nothing you cannot ground in an observation that actually happened.
Never reconstruct the goal from the execution trace. Read the contract.
来自
spec-interview/<slug>/
：
  • 合同：若存在
    SPEC.md
    则使用该文件；否则使用
    PLAN.md
    ，其中的
    Goal
    （目标）以及所有
    Done when
    （完成条件）的集合即为合同内容；
  • LEDGER.md
    ：记录已达成的状态，包含每条记录的
    Covers
    （覆盖范围）、证据和验证标签；
  • PLAN.md
    ：用于获取目标陈述以及任何未生成分类账记录的任务信息。
若没有分类账，需先从执行过程中重构关键事实再进行报告——但不得陈述任何无法基于实际观察结果佐证的内容。
绝不能从执行轨迹中重构目标。请直接阅读合同。

Step 1 — Classify the terminal state

步骤1：对终端状态进行分类

Do this before writing a word.
StatusMeaning
COMPLETED
Every required acceptance criterion is satisfied, with evidence
PARTIAL
A meaningful subset is done; one or more requirements remain unsatisfied
BLOCKED
Cannot continue without external access, information, permission, or a user decision
FAILED
The required state was not reached and no valid continuation is available
NO_OP
The requested state was already true; no change was needed
NO_OP
applies when every ledger entry is 
no_op
, or when 
PLAN.md
carries 
Status: no-op
and no tasks — in which case its 
Already true because
and 
Evidence
lines are your whole input. Report it plainly; do not dress an already-satisfied goal up as work.
Never upgrade 
PARTIAL
, 
BLOCKED
, 
FAILED
, or unverified work to 
COMPLETED
to produce a cleaner answer.
在撰写任何内容前完成此步骤。
状态（Status）含义
COMPLETED
所有要求的验收标准均已满足，且有证据支持
PARTIAL
已完成有意义的任务子集；仍有一项或多项要求未满足
BLOCKED
若无外部访问权限、信息、许可或用户决策，则无法继续推进
FAILED
未达成要求状态，且无有效的后续推进方案
NO_OP
请求的状态已为真；无需进行任何变更
当所有分类账记录均为
no_op
，或
PLAN.md
标注
Status: no-op
且无任何任务时，适用
NO_OP
状态——此时文件中的
Already true because
（已为真原因）和
Evidence
（证据）部分即为全部输入信息。需如实报告该状态，不得将已满足的目标包装成已完成的工作。
绝不能为了得到更“干净”的答案，将
PARTIAL
、
BLOCKED
、
FAILED
或未验证的工作升级为
COMPLETED
。

Step 2 — Compare the final state to the contract

步骤2：将最终状态与合同要求对比

Ask what the contract requires — not whether the executor said it finished.
Join ledger entries to criteria through each entry's 
Covers
. Build this internally; it is scaffolding, not output:
AC-001  satisfied     verified    integration test passed
AC-002  satisfied     verified    build passed
AC-003  satisfied     attested    the user confirmed the six accepted invitations
AC-004  unsatisfied   —           test database unavailable
AC-005  unverifiable  unverified  requires production access
COMPLETED
requires every criterion in the 
satisfied
column. Anything else downgrades the status.
When several entries cover one criterion — a task that ended 
partial
and the later task that finished its remainder — judge the criterion on the combined record, not the last entry alone. A later 
verified
entry supersedes an earlier 
unverified
one for the same criterion. An 
Unresolved
item that no later entry closed keeps the criterion unsatisfied, however many entries came after it. On a run with no SPEC, join on the 
Done when
text the ledger copied instead of on 
Covers
.
attested
— a person confirmed it — is satisfied. It is weaker than a machine check, so the report names it as confirmed rather than measured, but it does not block completion. Otherwise no work outside an automatable domain could ever complete.
The report is the projection of contract × final state × evidence — not of the executor's summary. This is what stops the implementer from being the sole judge of its own success.
需关注合同的要求——而非执行者声称任务已完成。
通过每条记录的
Covers
将分类账记录与验收标准关联。此关联仅作为内部框架，不纳入输出内容：
AC-001  satisfied     verified    integration test passed
AC-002  satisfied     verified    build passed
AC-003  satisfied     attested    the user confirmed the six accepted invitations
AC-004  unsatisfied   —           test database unavailable
AC-005  unverifiable  unverified  requires production access
COMPLETED
状态要求所有验收标准均处于
satisfied
（已满足）列。任何其他情况都会降级状态。
当多条记录覆盖同一验收标准时——比如某任务以
partial
结束，后续任务完成了剩余部分——需结合所有记录判断该标准的状态，而非仅看最后一条记录。针对同一标准，后续的
verified
记录会取代之前的
unverified
记录。但若某
Unresolved
（未解决）事项未被后续记录闭环，无论之后有多少条记录，该标准仍处于未满足状态。若执行过程中无SPEC文件，则通过分类账复制的
Done when
文本进行关联，而非
Covers
。
attested
（人工确认）属于已满足状态。它的可信度弱于机器检查，因此报告中需注明是人工确认而非机器测量，但这不会阻碍任务完成。否则，非自动化领域的工作将永远无法完成。
报告是合同×最终状态×证据的呈现——而非执行者的总结。这能避免执行者成为自身工作成功与否的唯一评判者。

Step 3 — Select material facts

步骤3：筛选关键事实

Report consequences, not activity.
A fact is material when omitting it could change the user's understanding of: what outcome was achieved, how behavior changed, whether the contract was met, whether the result was verified, what risk remains, what is still incomplete, what the user must do next, or whether compatibility changed.
NON-MATERIAL                      MATERIAL
opened five files          →      (nothing — omit)
ran a search               →      (nothing — omit)
retried a command          →      (nothing, unless it changed the outcome)
fixed formatting           →      (nothing — omit)
modified IUserRepository   →      the repository interface gained an email lookup,
                                  so other implementations must add it
The filename can follow the consequence for traceability. It never replaces it.
报告后果，而非活动过程。
某一事实属于关键事实的判定标准是：若省略该事实，可能会改变用户对以下内容的理解：已达成的结果、行为变化情况、是否符合合同要求、结果是否经过验证、仍存在的风险、未完成的事项、用户下一步需执行的操作，或兼容性是否发生变化。
非关键事实                      关键事实
opened five files          →      （无内容——省略）
ran a search               →      （无内容——省略）
retried a command          →      （无内容，除非该操作改变了结果）
fixed formatting           →      （无内容——省略）
modified IUserRepository   →      仓储接口新增了邮箱查询功能，因此该接口的其他实现版本需添加此功能
文件名可作为后果的补充以实现可追溯性，但绝不能替代后果描述。

Step 4 — Check coverage before compressing

步骤4：压缩前检查覆盖范围

Every material fact gets exactly one disposition: 
REPORT
, 
MERGE
(fully carried by another sentence), or 
OMIT
(implied by a reported fact, or has no user-visible consequence).
These may never be silently omitted when present:
- an unsatisfied acceptance criterion
- a failed verification
- an unverified completion claim
- changed external behavior
- a changed public contract or interface
- changed user data
- a destructive or irreversible action
- an unresolved blocker
- remaining risk
- required user action
- a material deviation from the contract
- an assumption that materially affected the result
The ledger carries these as 
State delta
, 
Unresolved
, 
Risk
, 
User action
, and 
Deviation
. Read all five; the outcome is not in 
State delta
alone.
This list is the semantic checksum. The question is never "is this concise?" — it is "does this concise version still carry every material fact?"
每个关键事实需被分配唯一的处理方式：
REPORT
（报告）、
MERGE
（完全融入另一句话）或
OMIT
（已被某报告事实所隐含，或无用户可见后果）。
若存在以下内容，绝不能默默省略：
- 未满足的验收标准
- 验证失败的情况
- 未经验证的完成声明
- 外部行为发生变化
- 公共合同或接口发生变化
- 用户数据发生变化
- 破坏性或不可逆操作
- 未解决的阻碍
- 仍存在的风险
- 用户需执行的操作
- 与合同要求存在重大偏差
- 对结果产生重大影响的假设
这些内容在分类账中以
State delta
（状态变化）、
Unresolved
（未解决）、
Risk
（风险）、
User action
（用户操作）和
Deviation
（偏差）的形式呈现。需通读这五类内容——结果并非仅存在于
State delta
中。
此列表是语义校验和。核心问题永远不是“这是否精简？”——而是“这个精简版本是否仍包含所有关键事实？”

Step 5 — Distinguish implemented from verified

步骤5：区分已实现与已验证

implemented
, 
verified
, 
attested
, and 
not verified
are four different states. Never collapse them.
A success claim must trace to an acceptance criterion satisfied, a check that passed, an observed state, a tool confirmation, an inspected artifact, or an explicit human confirmation.
WRONG   Everything is working correctly.
RIGHT   The parser change is implemented. Unit tests pass; integration tests were not run.
When verification is unavailable, say so in one clause. Do not hide it and do not apologize for it.
implemented
（已实现）、
verified
（已验证）、
attested
（已确认）和
not verified
（未验证）是四种不同的状态。绝不能将它们混为一谈。
成功声明必须可追溯至已满足的验收标准、通过的检查、观察到的状态、工具确认、经过检查的工件或明确的人工确认。
错误表述   Everything is working correctly.（一切正常。）
正确表述   The parser change is implemented. Unit tests pass; integration tests were not run.（解析器变更已实现。单元测试通过；未运行集成测试。）
当无法进行验证时，需用一个分句如实说明。不得隐瞒此情况，也无需为此致歉。

Step 6 — Order and render

步骤6：排序与呈现

Render in this order, and render only the sections that carry material information:
1. OUTCOME
2. MATERIAL CHANGE
3. VERIFICATION
4. RESIDUAL STATE
5. USER ACTION
Do not emit empty headings. A simple successful task is two sentences with no headings at all. Length follows the amount of material information — nothing else.
Compression order: coverage first, compression second, style third. No word limit; hard limits cause omission.
按以下顺序呈现内容，且仅呈现包含关键信息的章节：
1. OUTCOME（结果）
2. MATERIAL CHANGE（关键变更）
3. VERIFICATION（验证情况）
4. RESIDUAL STATE（剩余状态）
5. USER ACTION（用户操作）
不得输出空标题。一个简单的成功任务只需两句话，无需任何标题。报告长度取决于关键信息的数量——与其他因素无关。
压缩优先级：覆盖范围优先，压缩次之，格式最后。无字数限制；硬性字数限制会导致关键信息丢失。

Language rules

语言规则

  • One concept, one term, throughout.
  • Concrete nouns and verbs. Active voice when the actor matters.
  • Keep cause and consequence in the same sentence.
  • One proposition per sentence when combining them creates ambiguity.
  • Report state, not self: "The build passes" — not "I successfully ran the build."
  • No decorative transitions, no synonyms for variety, no generic success language.
AVOID                                  PREFER
Everything looks good.                 The requested endpoint is implemented.
The task was completed successfully.   The build passes.
Several improvements were made.        The integration test remains blocked by the
The code was updated accordingly.      unavailable database.
  • 一个概念对应一个术语，全程保持一致。
  • 使用具体的名词和动词。当执行者重要时，使用主动语态。
  • 需将原因和后果放在同一句话中。
  • 若合并句子会产生歧义，则每个句子仅表达一个命题。
  • 报告状态，而非自身行为："The build passes"（构建通过）——而非*"I successfully ran the build."*（我成功运行了构建。）
  • 不得使用装饰性过渡词，不得为了多样化使用同义词，不得使用通用的成功话术。
需避免                                  推荐使用
Everything looks good.                 The requested endpoint is implemented.（请求的端点已实现。）
The task was completed successfully.   The build passes.（构建通过。）
Several improvements were made.        The integration test remains blocked by the（集成测试因测试数据库不可用而受阻。）
The code was updated accordingly.      unavailable database.

Forbidden

禁止内容

- execution narration with no consequence
- unsupported success claims
- invented next steps
- restating the user's request before the outcome
- the same fact stated twice
- a hidden failure or a hidden unverified state
- 无后果的执行过程叙述
- 无依据的成功声明
- 编造后续步骤
- 在报告结果前重述用户的请求
- 同一事实重复陈述
- 隐藏失败或未验证状态

Examples

示例

Each shows a distinct terminal state or evidence class. Match the shape, not the domain.
COMPLETED
Implemented authenticated user lookup by email without changing the endpoint contract.
The build and 38 relevant tests pass.
COMPLETED with a compatibility consequence
Implemented authenticated user lookup by email. The repository interface now requires
an email lookup operation, so other implementations of that interface must add it.
The build and 38 relevant tests pass.
COMPLETED on attested evidence — a non-code run
All six candidate interviews are scheduled for the week of 3 March, each in a slot the
candidate accepted in writing. Two candidates required an evening slot, so the panel
runs until 19:00 on Tuesday and Thursday.
PARTIAL
The service implementation is complete and builds successfully. The integration test
could not run because the test database is unavailable, so the database-dependent
behavior remains unverified.
BLOCKED, user action required
Production deployment is blocked because production credentials are unavailable.
Version 2.4.0 passed the staging checks; production was not changed.
Provide production deployment access to continue.
NO_OP
No change was needed. Nullable reference types are already enabled globally for the project.
每个示例展示一种不同的终端状态或证据类型。需匹配格式，而非领域。
COMPLETED（已完成）
Implemented authenticated user lookup by email without changing the endpoint contract.
The build and 38 relevant tests pass.
COMPLETED with a compatibility consequence（已完成且存在兼容性影响）
Implemented authenticated user lookup by email. The repository interface now requires
an email lookup operation, so other implementations of that interface must add it.
The build and 38 relevant tests pass.
COMPLETED on attested evidence — a non-code run（基于人工确认证据的已完成——非代码类任务）
All six candidate interviews are scheduled for the week of 3 March, each in a slot the
candidate accepted in writing. Two candidates required an evening slot, so the panel
runs until 19:00 on Tuesday and Thursday.
PARTIAL（部分完成）
The service implementation is complete and builds successfully. The integration test
could not run because the test database is unavailable, so the database-dependent
behavior remains unverified.
BLOCKED, user action required（受阻，需用户操作）
Production deployment is blocked because production credentials are unavailable.
Version 2.4.0 passed the staging checks; production was not changed.
Provide production deployment access to continue.
NO_OP（无需操作）
No change was needed. Nullable reference types are already enabled globally for the project.

Persisting the report

报告持久化

Render the report in the conversation. Also write it to 
spec-interview/<slug>/REPORT.md
with the status and date in a header, so the folder holds the complete record of the work.
Skip the file when there is no working directory — for a one-off report, the conversation is the delivery.
Design rationale — non-normative, and older than this skill: docs/completion-reporter-design.md. It explains why the protocol is shaped this way, at much greater length, and it predates the 
attested
verification label. Where the two disagree, this file wins.
在对话中呈现报告。同时将报告写入
spec-interview/<slug>/REPORT.md
，并在头部包含状态和日期，以便该文件夹保存完整的工作记录。
若不存在工作目录则跳过文件写入——对于一次性报告，对话即为交付渠道。
设计依据——非规范性内容，且早于此Skill：docs/completion-reporter-design.md。该文档详细解释了此协议如此设计的原因，且撰写时间早于
attested
验证标签。若本文档与该设计依据存在冲突，以本文档为准。