feature-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

feature-docs

Feature docs preserve what a feature does, why choices were made, and what remains unverified for a reader without the original conversation. The local-markdown configuration of Matt Pocock's skills uses

.scratch/<feature>/

; consult

docs/agents/issue-tracker.md

when present rather than assuming every tracker uses local files.

Write three human documents under

docs/<feature>/feature-docs/

File	Owns
`overview.md`	User problem, current capabilities, contracts, navigation and verification summary
`decisions.md`	Choices, recorded reasons, rejected alternatives and unresolved intent conflicts
`tickets.md`	Delivery slices, acceptance criteria, evidence and remaining checks
`sources.json`	Script-owned source, document and evidence baselines; never hand-edit

One fact has one home; other files link to it by decision/ticket ID. Remove template writing instructions from finished docs; retain useful navigation and status legends. Use the local feature slug. The script is

bash scripts/feature-docs.sh

; read

--help

for command syntax. Read

references/example.md

when an evidence row or finished document is unclear.

Feature 文档用于记录某个 Feature 的功能、做出选择的原因，以及在无法查看原始对话的读者看来仍未得到验证的事项。Matt Pocock 的 skill 使用的本地 Markdown 配置采用

.scratch/<feature>/

；如果存在

docs/agents/issue-tracker.md

，应查阅该文件，而不要假定每个 issue tracker 都使用本地文件。

在

docs/<feature>/feature-docs/

下编写三份面向人的文档：

文件	负责内容
`overview.md`	用户问题、当前能力、契约、导航和验证摘要
`decisions.md`	选择、记录的理由、已否决的替代方案和尚未解决的意图冲突
`tickets.md`	交付切片、验收标准、证据和剩余检查
`sources.json`	由脚本管理的来源、文档和证据基线；切勿手动编辑

一个事实只应有一个归属位置；其他文件通过 decision/ticket ID 链接到它。完成后移除模板中的编写说明；保留有用的导航和状态图例。使用本地 feature slug。脚本为

bash scripts/feature-docs.sh

；命令语法请阅读

--help

。如果证据行或完成后的文档含义不清，请阅读

references/example.md

。

Evidence and decisions

证据与决策

Code inspected supports only what the opened file/symbol demonstrates. Test passed requires an actual result, command, scope and date. Runtime verified requires an observed scenario, environment and date. Inherited results name their source and say not rerun. A test file is code evidence, not a passing result. Mark unsupported claims unverified, with the check still needed.

Acceptance criteria determine suitable evidence: inspection may establish a static contract; a performance limit needs measurement. Source triage labels and discovery

resolved

states are not delivery evidence. Ticket states and decision states are defined in their templates.

Code establishes observed implementation; explicit agreements establish accepted intent. Keep a discrepancy visible until resolved. Record undocumented rationale as Not recorded and unknown historical dates as Unknown. An observed implementation choice is Observed, not automatically Accepted. A source's disappearance changes provenance; withdrawal requires evidence of cancellation. Preserve superseded decisions and withdrawn tickets.

Code inspected 只能支持已打开的文件或符号所明确证明的内容。Test passed 必须包含实际结果、命令、范围和日期。Runtime verified 必须包含观察到的场景、环境和日期。继承的结果应注明其来源，并标为 not rerun。测试文件属于代码证据，而不是测试通过的结果。将缺乏支持的说法标为 unverified，并写明仍需进行的检查。

验收标准决定适用的证据类型：代码检查可以确立静态契约，而性能限制需要测量。来源分类标签和 discovery 中的

resolved

状态不能作为交付证据。Ticket 状态和 decision 状态在各自的模板中定义。

代码确立的是观察到的实现；明确的约定确立的是已接受的意图。解决前应始终保留差异。将未记录的理由标为 Not recorded，将未知的历史日期标为 Unknown。观察到的实现选择属于 Observed，不会自动成为 Accepted。来源消失会改变其溯源信息；撤回则需要取消的证据。保留已被取代的决策和已撤回的 ticket。

Pick the mode

选择模式

Full or partial implementation needs its first record → WRITE.
The user points at existing documentation → CONVERT.
Sources, implementation or evidence changed, or the user requests reconciliation → SYNC.
Before speccing, ticketing or changing a documented feature → LOOKUP.

Use the existing feature folder for later changes. A fix affecting no documented claim needs no content edit. When the repo lacks

docs/FEATURES.md

, offer the optional retrieval setup in

references/setup.md

after writing the first record.

完整或部分实现需要建立首份记录 → WRITE。
用户指向现有文档 → CONVERT。
来源、实现或证据发生变化，或用户要求协调 → SYNC。
在编写 spec、创建 ticket 或变更已记录的 Feature 之前 → LOOKUP。

后续变更使用现有的 feature 文件夹。如果某项修复不影响任何已记录的说明，则无需修改内容。当仓库缺少

docs/FEATURES.md

时，可在写入首份记录后，提供

references/setup.md

中可选的检索设置。

WRITE

Read the spec, tickets including comments, and relevant build decisions. For
```
map.md
```
, typed discovery tickets, research/prototype answers or Fleet evidence, read
```
references/sources.md
```
. Classify inputs before mapping them: an answered research question is not a shipped capability.
Run
```
new <repo> <feature>
```
. Read implementation and available verification evidence until every delivery criterion has an evidence assessment or an explicit gap. Preserve only durable conclusions from discovery.
Fill the templates. Aim for a 300–600-word overview without padding; complex features may need more. Cite repository-relative files actually inspected. Put acceptance detail in tickets and rationale in decisions; overview gaps link to those IDs. Record significant agreed choices and meaningful deviations, not every incidental implementation detail.
Run
```
check <repo> <feature>
```
and resolve its structural findings. Review the claims yourself: the command cannot establish semantic truth.
Run
```
stamp <repo> <feature> --evidence <file> ...
```
with the implementation, test or configuration files inspected to support the record. The first version-2 stamp requires a nonempty explicit list; each
```
--evidence
```
names one file. Later omission reuses the recorded list; supplying a list replaces it. Source documents are tracked separately. Use
```
--source <dir>
```
for a different local source folder, or
```
--evidence-only
```
for conversion without one.
Report written files, partial/planned work, verification gaps and glossary/ADR candidates. Stamping records reviewed baselines; it does not validate behavior.

阅读 spec、ticket（包括评论）以及相关的构建决策。对于
```
map.md
```
、带类型的 discovery ticket、研究或原型答复以及 Fleet 证据，应阅读
```
references/sources.md
```
。映射前先对输入进行分类：已得到回答的研究问题并不等同于已交付的能力。
运行
```
new <repo> <feature>
```
。阅读实现和可用的验证证据，直至每项交付标准都有证据评估或明确的缺口说明。仅保留 discovery 阶段得出的长期有效结论。
填写模板。概述应控制在 300–600 词，避免灌水；复杂 Feature 可能需要更长篇幅。引用实际检查过的仓库相对路径文件。将验收细节放入 ticket，将理由放入 decision；overview 中的缺口应链接到相应 ID。记录重要的既定选择和有意义偏差，而不是每个偶然的实现细节。
运行
```
check <repo> <feature>
```
并解决其结构性问题。自行复核各项说明：该命令无法证明语义正确性。
使用已检查的实现、测试或配置文件运行
```
stamp <repo> <feature> --evidence <file> ...
```
，以支持该记录。首次执行 version-2 stamp 时，必须提供非空的显式文件列表；每个
```
--evidence
```
指向一个文件。后续省略该列表时会复用已记录的列表；提供列表则会替换原列表。源文档单独跟踪。对于不同的本地来源文件夹，使用
```
--source <dir>
```
；对于没有来源的转换，使用
```
--evidence-only
```
。
报告已写入的文件、部分完成或计划中的工作、验证缺口，以及 glossary/ADR 候选项。Stamp 会记录已审查的基线，但不会验证行为。

SYNC

Run
```
status <repo> [<feature>]
```
. Distinguish source, document and evidence drift, missing files, legacy REVIEW REQUIRED, and planned/partial reminders. Matching baselines are mechanical checks, not proof of correctness. An explicit reconciliation request or known implementation change still warrants review.
Read changed sources and affected evidence, using
```
diff
```
for source changes. Reconcile changed claims in their owning files. Comments may revise an agreement; chronology alone does not establish approval. Keep unresolved contradictions attributed. For moved code, verify the replacement path and update citations. Removal alone supplies neither a reason nor cancellation.
Reassess affected criteria, including partial/planned tickets. Update implementation and verification independently. A new accepted choice gets a new decision ID; supersede the earlier accepted choice only when replacement is established.
Run
```
check
```
. Update
```
Updated:
```
only when document content changes. Stamp after reconciliation when a baseline changes; supply the complete evidence list if membership changed. With missing local sources, use
```
--evidence-only
```
to retain the last source baseline while updating documents/evidence. A source-free conversion remains source-free on later stamps.
Report reconciled changes and unresolved gaps. If neither content nor baselines changed, leave dates and stamps untouched. Missing scratch material is not a reason to discard the tracked record.

运行
```
status <repo> [<feature>]
```
。区分来源、文档和证据漂移、缺失文件、旧版 REVIEW REQUIRED 标记，以及计划中或部分完成的提醒。基线匹配仅表示机械检查通过，并不能证明内容正确。用户明确要求协调或已知实现发生变化时，仍需进行审查。
阅读发生变化的来源和受影响的证据，并使用
```
diff
```
检查来源变更。在各自所属文件中协调发生变化的说明。评论可能修订约定；仅凭时间顺序不能证明已获得批准。未解决的矛盾应保留并注明归属。代码移动后，应验证新的路径并更新引用。移除内容本身既不能说明原因，也不能证明取消。
重新评估受影响的验收标准，包括部分完成或计划中的 ticket。分别更新实现和验证信息。新达成的已接受选择应获得新的 decision ID；只有在替代选择已经确立后，才能取代先前已接受的选择。
运行
```
check
```
。仅当文档内容发生变化时才更新
```
Updated:
```
。协调后，如果基线发生变化，则执行 stamp；如果证据列表的成员发生变化，则提供完整证据列表。缺少本地来源时，使用
```
--evidence-only
```
在更新文档和证据的同时保留上一个来源基线。没有来源的转换在后续 stamp 中仍应保持无来源状态。
报告已协调的变更和未解决的缺口。如果内容和基线均未发生变化，则不要修改日期和 stamp。缺少 scratch 材料并不构成丢弃已跟踪记录的理由。

CONVERT

Read the supplied material and
```
references/convert.md
```
. Use one folder per feature; resolve genuinely ambiguous feature boundaries before writing.
Run
```
new
```
, map content into the three files, and check claims against appropriate evidence. Preserve relevant proposed choices and conflicts. Mark claims the available material cannot settle as unverified.
Record origins on the overview's
```
Source:
```
line. Run
```
check
```
, then stamp with explicit evidence and a continuing local source folder, or
```
--evidence-only
```
when none exists.
Leave originals in place. Report their paths and any agent pointers needing repointing; remove originals only with authorization.

阅读所提供的材料和
```
references/convert.md
```
。每个 Feature 使用一个文件夹；写入前先解决确实存在歧义的 Feature 边界。
运行
```
new
```
，将内容映射到三个文件中，并根据适当证据检查各项说明。保留相关的拟议选择和冲突。将现有材料无法确定的说明标为 unverified。
在 overview 的
```
Source:
```
行记录来源。运行
```
check
```
，然后使用显式证据和后续继续使用的本地来源文件夹执行 stamp；如果不存在来源，则使用
```
--evidence-only
```
。
保留原始文件。报告其路径以及需要重新指向的 Agent 指针；只有在获得授权后才移除原始文件。

LOOKUP

Read
```
docs/FEATURES.md
```
, or list
```
docs/*/feature-docs/
```
, and select the affected feature.
Read its overview for context, then decisions before proposing changes. Read tickets for relevant criteria, evidence and unfinished work.
Cite decisions in the new spec/ticket: “builds on D3” or “proposes to supersede D5.” Preserve current accepted intent until an approved change replaces it; reconcile the record through SYNC.

阅读
```
docs/FEATURES.md
```
，或列出
```
docs/*/feature-docs/
```
，并选择受影响的 Feature。
阅读其 overview 以了解背景，然后在提出变更前阅读 decisions。阅读 ticket 中相关的验收标准、证据和未完成工作。
在新的 spec/ticket 中引用 decision，例如“基于 D3 构建”或“提议取代 D5”。在经批准的变更取代当前已接受的意图之前，应保留现有意图，并通过 SYNC 协调记录。

Glossary and ADRs

Glossary 与 ADR

Find domain conventions through

docs/agents/domain.md

; otherwise check the root glossary and

docs/adr/

. Use established terms. Cite existing ADRs instead of duplicating their reasoning; an ADR remains authoritative for the decision it governs. Flag contradictions rather than silently erasing either source.

Report new domain terms as glossary candidates and cross-feature contracts or conventions as ADR candidates. Keep feature-local records concise; use the repo's existing process for promotion.

通过

docs/agents/domain.md

查找领域约定；否则检查根目录 glossary 和

docs/adr/

。使用既有术语。引用现有 ADR，而不是重复其推理过程；ADR 对其管辖的决策仍具有权威性。发现矛盾时应明确标记，而不是悄然删除任一来源。

将新的领域术语报告为 glossary 候选项，将跨 Feature 的契约或约定报告为 ADR 候选项。保持 Feature 本地记录简洁；沿用仓库现有流程将其提升为正式文档。