Back to Details

evidence-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evidence-backed documentation

基于证据的文档

A claim is documentation only when it carries the means to check it. This skill is the standard and the map: ten canons, and where each is defined, enforced and seeded.
It is a navigator, not a second copy. Every law below has exactly one home — that is canon 3, and a navigator that restated the doctrine would break the rule it is indexing. The full statement of each canon, its rationale and its enforcement live in 
documentation.md
 → The canons.
只有当内容附带可验证的依据时，才能称之为文档。 本技能是标准与指引：包含十条准则，以及每条准则的定义、执行方式和来源。
它是一个导航工具，而非重复副本。以下每条准则都有唯一的来源——这正是准则3的要求，若导航工具重述规范，便会违背其索引的规则。每条准则的完整说明、原理及执行细节请查看
documentation.md
 → 准则部分。

The ten canons

十条准则

  1. A claim carries its address — 
    file:line
    , a command with its output, a test name; a lesson names its commit.
  2. Numbers are computed, never restated.
  3. Every fact has exactly one home — others link, never restate.
  4. A reference resolves from where the document is read — not from where it lives.
  5. Green nobody watched turn red is not evidence.
  6. A check proves its scope and nothing beyond it.
  7. Silence is not a pass — ask what a mechanism prints when it did not look.
  8. An estimate is never announced as a measurement — a rule states its evidence condition.
  9. What was not checked is printed beside what was.
  10. The document ships in the change that made it true — and a correction is appended, never written over.
They are epistemic: what makes a claim documentation. The operational layer — what to do at a given trigger, with a check and an exit criterion — is 
learned.md
. When the two seem to say the same thing, the canon is the why and the rule is the how.
  1. 内容附带定位信息 —— 
    file:line
    、带输出的命令、测试名称；经验教训需标注对应的提交记录。
  2. 数据需计算得出，不得重复转述。
  3. 每个事实仅有唯一来源 —— 其他内容仅可链接，不得重复转述。
  4. 引用需从文档阅读位置解析 —— 而非文档存储位置。
  5. 无人关注的成功结果不算证据。
  6. 验证仅能证明其覆盖范围，不涉及其他内容。
  7. 无反馈不等于通过 —— 需明确机制未检查时的输出内容。
  8. 估算不得当作实测结果发布 —— 规则需明确其证据条件。
  9. 未检查内容需与已检查内容一并列出。
  10. 文档随使其生效的变更一同发布 —— 修正内容需追加，不得覆盖原文。
这些是认知层面的要求：界定了何为有依据的文档。操作层面——即特定触发场景下的行动、验证方式及退出标准——请查看
learned.md
。当两者内容看似重叠时，准则是原因，规则是执行方法。

Where next

下一步指引

You are about to…ReadBecause
set a project's documentation up from nothing
documentation.md
 → The inventory		four questions answered before the first line of work
record a decision so it survives its authorRegisters and ids + 
templates/decisions.md
append-only ids, edge markers, one decision home
change something and not orphan the docsThe Doc Loop + The propagation matrixwhich documents a change owes, starting with the meta-row
decide where a fact belongsSingle source of truthtwo homes disagree the day one of them is updated
build a check that cannot lie
gates.md
three axes, the enforcement ladder, progressive arming, probing
trust a mechanism that reports success
gates.md
 → False success		the failure that removes the reason to look
wire a check into the agent's own tooling
hooks.md
the hook contract, and why a crashed guard allows the action
audit documentation a project already has
setup.md
seven passes, cheapest first, output is a fix plan
carry a lesson to the next run
retrospective.md
stamp first (the cold trigger reads it), then prune to a cap of ten; every lesson names its commit
seed a gate into a host project
templates/docgate.sh
it seeds green: dormant where there is no input yet
claim that an agent behaves
tdd.md
→ When the thing under test is an agent — named rather than linked, because this navigator's out-of-directory links break wherever a packager ships this skill alone		the address is a trace id and the assertion that ran (canon 1); a judge nobody watched disagree is a green nobody watched turn red (canon 5)
take a whole change through to acceptance
task-pipeline
this skill is the standard; that one is how a change reaches the repository
你即将要…阅读内容原因
从零开始搭建项目文档体系
documentation.md
 → 清单部分		开始工作前需明确四个核心问题
记录决策以确保其不受作者离职影响登记册与ID + 
templates/decisions.md
仅追加式ID、边界标记、决策唯一来源
变更内容且不导致文档脱节文档循环 + 传播矩阵变更需同步的文档范围，从元数据行开始
确定事实的归属位置单一事实来源若存在两个来源，其中一个更新时必然出现分歧
构建可靠的验证机制
gates.md
三个维度、执行层级、渐进式启用、探查机制
信任报告成功的机制
gates.md
 → 虚假成功		此类失败会消除进一步检查的必要性
将验证机制接入Agent工具链
hooks.md
钩子合约，以及为何崩溃的防护会允许操作执行
审计项目现有文档
setup.md
七个检查步骤，从成本最低的开始，输出修复方案
将经验教训带入下一轮工作
retrospective.md
先标记（冷触发时读取），再精简至最多十条；每条经验教训需标注对应的提交记录
在宿主项目中植入文档准入机制
templates/docgate.sh
初始状态为绿色：无输入时处于休眠状态
声称Agent行为合规
tdd.md
→ 当测试对象为Agent时 —— 此处仅命名而非链接，因为本导航工具的跨目录链接在打包工具单独分发此技能时会失效		定位信息为追踪ID及执行的断言（准则1）；无人关注的判定分歧属于“无人关注的成功结果变失败”（准则5）
完成完整变更的验收流程
task-pipeline
本技能是标准，而该技能是变更进入代码库的流程指引

When this applies

适用场景

The boundary is "it will be read as true." A decision record, a README, an acceptance report, a runbook, a changelog for users, an audit finding, a claim that something was verified.
Not through this skill: a draft, thinking out loud, an answer in chat, a commit message, a code comment. Demanding a 
file:line
for "let me check that" is the fastest way to teach an agent to route around the rule where it actually protects something.
Refusal phrase — "без доков" / "on my word". It works on a task that would otherwise pass through here: do it directly and say out loud that the claim is unbacked, rather than presenting an estimate as a measurement (canon 8).
边界是“内容会被当作事实”。包括决策记录、README、验收报告、运行手册、面向用户的变更日志、审计结果、声称已验证的内容。
不适用场景：草稿、即兴想法、聊天回复、提交信息、代码注释。若对“我确认一下”这类内容要求
file:line
定位，会导致Agent在规则实际需要保护的场景下绕开规则。
拒绝用语 —— "без доков" / "on my word"。此用语可用于原本会进入本流程的任务：直接执行操作，并明确说明内容无依据，而非将估算当作实测结果发布（准则8）。

The one test

唯一测试标准

Before a document ships, read it for the sentence that would embarrass you if someone asked "how do you know?" — and either give that sentence its address, or delete it. Everything above is that question, made mechanical.
文档发布前，通读并找出若有人问*“你怎么知道的？”*会让你尴尬的句子——要么为该句子添加定位依据，要么删除它。以上所有规则都是将这个问题转化为可执行的机械流程。