facts-discover

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

facts-discover

You are a fact sheet maintainer. Your job is to scan the codebase, classify every fact by lifecycle stage, and add missing truths — in a single session.

你是一名事实表维护者。你的工作是在单次会话中扫描代码库、按生命周期阶段对每个事实进行分类，并补充缺失的真实信息。

When to use this skill

何时使用此技能

This skill classifies facts and syncs the fact sheet with reality. Only use when the user explicitly asks to discover, audit, or sync facts. If the user says "work on facts" or "add facts", they want to define spec — use the

facts

skill instead, not this one.

此技能用于对事实进行分类，并使事实表与实际情况保持同步。仅当用户明确要求发现、审计或同步事实时使用。如果用户说“处理事实”或“添加事实”，他们是想要定义规范——请改用

facts

技能，而非本技能。

Goal

目标

After running this skill, every fact should have the correct lifecycle tag:

@draft
— the fact is vague or high-level; needs refinement before it can be implemented (e.g. "this project supports stripe payments")
@spec
— the fact is precise and actionable, but the code doesn't back it up yet (e.g. "POST /payments creates a Stripe PaymentIntent and returns the client secret")
@implemented
— the fact is true and the codebase proves it
Untagged — ground truth discovered from the codebase; already verified by observation

Additionally, add facts about important truths not yet in the fact sheet (these go in untagged, since they're already true), fix inaccurate facts, and remove obsolete ones.

Facts with good validation commands are self-enforcing — they catch regressions automatically. But a manual fact is better than a fact with a useless command. A command that always passes regardless of whether the fact is true gives false confidence and is worse than no command at all. Only add a command when it genuinely tests the claim.

运行此技能后，每个事实都应带有正确的生命周期标签：

@draft
——事实模糊或属于高层级描述；需要细化后才能实现（例如：“本项目支持Stripe支付”）
@spec
——事实精确且可执行，但代码尚未实现该内容（例如：“POST /payments会创建一个Stripe PaymentIntent并返回客户端密钥”）
@implemented
——事实真实存在，且代码库可证明这一点
未标记——从代码库中发现的基本事实；已通过观察验证

此外，需补充事实表中尚未涵盖的重要真实信息（这些信息无需标记，因为它们已被证实为真），修正不准确的事实，并移除过时的内容。

带有有效验证命令的事实具有自我约束力——它们会自动捕获回归问题。但手动维护的事实比带有无用命令的事实更有价值。无论事实是否真实都始终通过的命令会带来虚假的信心，比没有命令更糟糕。只有当命令能真正验证声明时才添加它。

Process

流程

1. Load the current fact sheet

1. 加载当前事实表

Run

facts list

to see all current facts. Note which sections exist and what they cover.

Run

facts check

to see which command-facts pass and which fail. Failing facts are candidates for removal or correction.

For each manual fact (

in the output): read what it claims, check the relevant code, and classify it based on what you actually find — not on the label alone. Manual facts are often the most important ones because they describe behavior that resists simple command validation.

运行

facts list

查看所有现有事实。记录已有的章节及其涵盖内容。

运行

facts check

查看哪些带命令的事实通过验证，哪些失败。验证失败的事实是移除或修正的候选对象。

对于每个手动事实（输出中的

）：阅读其声明内容，检查相关代码，并根据实际发现进行分类——不要仅依赖现有标签。手动事实通常是最重要的，因为它们描述了难以通过简单命令验证的行为。

2. Scan the codebase

2. 扫描代码库

Build a mental model of the project by tracing what it does, not just how it's structured. Focus on end-user-visible behavior — the features, workflows, and contracts that someone using or integrating with this project would care about.

Use subagents to scan different areas in parallel for large codebases. Assign each subagent a feature area or module, not a structural category like "dependencies" or "build system." For each area, the subagent should answer:

What does this do? — describe the behavior from the user's perspective
What are the inputs and outputs? — API contracts, CLI flags, file formats, event shapes
What are the edge cases? — error handling, boundary conditions, fallback behavior
What would break if this were reimplemented naively? — non-obvious invariants, ordering dependencies, timing constraints, implicit contracts between components
What are the key concepts? — named types, domain abstractions, data structures. What does this module call things, and how do those names relate to concepts in other modules?

Each subagent should report back behavioral observations — not "this file exists" or "this uses library X", but "when X happens, Y results" and "if X fails, the system does Y."

Do not waste facts on structural trivia. "The project has a src/auth.rs file" is not a useful fact. "Expired tokens are rejected with 401 and the response includes a

reason

field" is.

通过追踪项目实际功能而非仅结构来构建对项目的认知模型。重点关注终端用户可见的行为——即使用或集成此项目的人会关心的功能、工作流和契约。

对于大型代码库，使用子代理（subagents）并行扫描不同区域。为每个子代理分配功能区域或模块，而非“依赖项”或“构建系统”这类结构分类。针对每个区域，子代理应回答：

此模块的功能是什么？——从用户视角描述行为
输入和输出是什么？——API契约、CLI标志、文件格式、事件结构
边缘情况有哪些？——错误处理、边界条件、回退行为
如果重新实现此模块时采用简单方法，会出现哪些问题？**——非显式的不变量、顺序依赖、时序约束、组件间的隐式契约
核心概念是什么？——命名类型、领域抽象、数据结构。此模块如何命名事物，这些名称与其他模块中的概念有何关联？

每个子代理应反馈行为观察结果——不是“此文件存在”或“此模块使用库X”，而是“当X发生时，会产生Y结果”和“如果X失败，系统会执行Y操作”。

不要在无关紧要的结构细节上浪费事实。“项目包含src/auth.rs文件”不是有用的事实。“过期令牌会被拒绝并返回401状态码，响应中包含

reason

字段”才是。

2b. Build the project ontology

2b. 构建项目本体

Before classifying or writing facts, establish the project's key entities and relationships as facts in a

## domain

section of the main

.facts

file. This vocabulary becomes the canonical naming for all other facts in the sheet.

From the subagent scan results, identify the named concepts that appear across multiple parts of the codebase — these are the project's entities.
For each entity, write a definition fact using the pattern
```
a <Name> is <definition>
```
. Use the name the codebase actually uses (the struct name, the type name, the term in the docs), not an invented abstraction.
Identify the important relationships between entities — what contains what, what produces or consumes what, what validates or transforms what. Write these as relation facts using the defined entity names in natural declarative statements. There is no rigid grammar — the connection should be specific and use entity names consistently.
Check the existing fact sheet for inconsistent terminology. If the same concept is called "sheet" in one fact and "fact file" in another, standardize on one term and edit the inconsistent facts.

If a

## domain

section already exists, update it — add missing entities, remove obsolete ones, correct inaccurate definitions. The domain section evolves with the codebase.

Quality filters:

Only define entities that appear as concepts across multiple areas of the codebase. If a concept is confined to a single function and won't appear in other facts, it doesn't need a domain definition. After writing behavioral facts in Steps 3–4, prune any domain entity that turned out to be unreferenced.
Relations capture the topology — the wiring diagram between entities that you can't see from individual behavioral facts. A domain section with only entity definitions and zero relations is a parts list without assembly instructions. If you defined entities, ask: how do they connect? What produces, consumes, contains, or transforms what?
Use the actual names from the code. If the codebase calls it
```
FactSheet
```
, the fact uses
```
FactSheet
```
. Do not normalize to "Fact Sheet" unless the project's own documentation does.
A domain section typically has 5–15 entities and a handful of relations. If you're defining 20+ entities, you are likely including implementation details rather than domain concepts. If no concepts pass the cross-cutting threshold, skip the domain section entirely — not every project needs one.

For projects that split facts across multiple files (

cli.facts

api.facts

), the

## domain

section goes in the main

.facts

file since it applies project-wide.

Example (for a payment processing project):

undefined

在对事实进行分类或编写新事实之前，先在主

.facts

文件的

## domain

章节中建立项目的核心实体和关系作为事实。此词汇表将成为事实表中所有其他事实的标准命名规范。

从子代理的扫描结果中，识别出在代码库多个部分出现的命名概念——这些是项目的核心实体。
对于每个实体，使用
```
a <Name> is <definition>
```
的格式编写定义事实。使用代码库实际使用的名称（结构体名称、类型名称、文档中的术语），而非自行创造的抽象名称。
识别实体之间的重要关系——哪些实体包含其他实体，哪些实体生成或消费其他实体，哪些实体验证或转换其他实体。使用已定义的实体名称，以自然的声明式语句编写这些关系事实。无需严格遵循语法规则，但关联内容应具体，且实体名称使用一致。
检查现有事实表中是否存在不一致的术语。如果同一概念在一个事实中称为“sheet”，在另一个事实中称为“fact file”，则统一使用其中一个术语，并修改不一致的事实。

如果

## domain

章节已存在，则对其进行更新——添加缺失的实体，移除过时的实体，修正不准确的定义。领域章节会随代码库一同演进。

质量筛选标准：

仅定义在代码库多个区域中作为概念出现的实体。如果某个概念仅局限于单个函数，不会出现在其他事实中，则无需在领域中定义。在步骤3-4编写行为事实后，删除任何未被引用的领域实体。
关系应体现拓扑结构——即从单个行为事实中无法看出的实体间连接关系。只有实体定义而没有关系的领域章节，就像没有装配说明的零件清单。如果定义了实体，请思考：它们如何连接？哪些实体生成、消费、包含或转换其他实体？
使用代码中的实际名称。如果代码库中称为
```
FactSheet
```
，则事实中也使用
```
FactSheet
```
。除非项目自身文档使用“Fact Sheet”，否则不要标准化为此名称。
领域章节通常包含5-15个实体和少量关系。如果定义了20个以上的实体，可能是将实现细节而非领域概念包含在内。如果没有概念符合跨区域使用的标准，则完全跳过领域章节——并非每个项目都需要此章节。

对于将事实拆分到多个文件（如

cli.facts

、

api.facts

）的项目，

## domain

章节应放在主

.facts

文件中，因为它适用于整个项目。

示例（针对支付处理项目）：

undefined

domain

a PaymentIntent is a Stripe object representing a single charge attempt
a Webhook is an incoming HTTP POST from Stripe reporting a payment event
a DeadLetter is a Webhook that exhausted all retry attempts without acknowledgement
a Merchant is a registered business account that receives payments
a PaymentIntent produces Webhooks on status changes
a Webhook becomes a DeadLetter after 3 failed delivery attempts
a Merchant owns PaymentIntents


**Anti-example** (what not to write):

a PaymentIntent is a Stripe object representing a single charge attempt
a Webhook is an incoming HTTP POST from Stripe reporting a payment event
a DeadLetter is a Webhook that exhausted all retry attempts without acknowledgement
a Merchant is a registered business account that receives payments
a PaymentIntent produces Webhooks on status changes
a Webhook becomes a DeadLetter after 3 failed delivery attempts
a Merchant owns PaymentIntents


**反例**（不应编写的内容）：

domain

a Rust source file contains module definitions
parser.rs is responsible for parsing
the project has a CLI that accepts commands


These are structural trivia that restate file existence, not domain concepts.

a Rust source file contains module definitions
parser.rs is responsible for parsing
the project has a CLI that accepts commands


这些是重复文件存在性的结构细节，而非领域概念。

3. Classify facts by lifecycle stage

3. 按生命周期阶段分类事实

For each existing fact, check it against the codebase and assign the correct lifecycle tag:

True and code-backed → tag

@implemented

facts edit <id> --add-tag "implemented"

Precise and actionable, but code doesn't exist yet → tag
```
@spec
```
:
```
facts edit <id> --add-tag "spec"
```
Vague or high-level, not yet actionable → tag
```
@draft
```
:
```
facts edit <id> --add-tag "draft"
```
Partially true — edit the label first, then classify:
```
facts edit <id> --label "corrected statement"
```
False or obsolete — remove:
```
facts remove <id>
```
Missing validation — the fact could be verified by a command but lacks one:
```
facts edit <id> --command "check command"
```

When a fact already has a lifecycle tag, verify it's still correct. An

@implemented

fact whose code was removed should be reclassified to

@spec

. A

@draft

fact that was refined elsewhere should be updated.

When removing facts, check if the concept has evolved rather than disappeared — edit instead of remove+add when the same idea persists in a new form.

When editing fact labels, use the vocabulary established in

## domain

. If a fact says "file" but the domain section defines the concept as "FactSheet", update the label to use "FactSheet" for consistency.

针对每个现有事实，对照代码库检查并分配正确的生命周期标签：

真实且有代码支撑 → 标记

@implemented

：

facts edit <id> --add-tag "implemented"

精确且可执行，但代码尚未实现 → 标记
```
@spec
```
：
```
facts edit <id> --add-tag "spec"
```
模糊或高层级描述，尚未可执行 → 标记
```
@draft
```
：
```
facts edit <id> --add-tag "draft"
```
部分真实 —— 先编辑标签，再分类：
```
facts edit <id> --label "corrected statement"
```
虚假或过时 —— 移除：
```
facts remove <id>
```
缺少验证 —— 事实可通过命令验证但未添加：
```
facts edit <id> --command "check command"
```

如果事实已带有生命周期标签，需验证其是否仍然正确。已标记

@implemented

但代码已被移除的事实应重新分类为

@spec

。已标记

@draft

但已在其他地方细化的事实应更新。

移除事实时，需检查概念是否已演进而非消失——如果同一想法以新形式存在，应编辑而非移除后重新添加。

编辑事实标签时，使用

## domain

章节中确立的词汇。如果某个事实使用“file”但领域章节中将该概念定义为“FactSheet”，则更新标签为“FactSheet”以保持一致性。

3b. Add commands to manual facts

3b. 为手动事实添加命令

Go through manual facts and ask: can this be checked with a short shell command that would actually fail if the fact became false?

That second part is the hard filter. Before adding a command, apply this test:

If someone changed the codebase so this fact was no longer true, would the command fail?

If the answer is no — or only maybe — leave the fact manual.

逐一检查手动事实，并思考：是否可以用一个简短的Shell命令来验证该事实，且当事实不再真实时命令会失败？

第二部分是严格的筛选条件。添加命令前，请应用以下测试：

如果有人修改代码库导致此事实不再真实，命令会失败吗？

如果答案是否定的——或只是可能——则保持该事实为手动维护状态。

What makes a command meaningful

有效命令的特征

A command validates a fact when it checks the claim itself, not just the existence of related code. The command should be:

Falsifiable — would actually break if the fact became untrue
Fast — runs in under a second (grep, test, jq, wc, head)
Idempotent — read-only, no side effects
Stable — does not break on unrelated changes (avoid line-count checks, match patterns not positions)
Silent on success — exit 0 means the fact holds, non-zero means it doesn't

Good commands check concrete, specific things:

undefined

当命令能检查声明本身而非仅相关代码的存在时，它才能验证事实。命令应具备以下特征：

可证伪——当事实不再真实时确实会失败
快速——运行时间少于1秒（如grep、test、jq、wc、head）
幂等——只读，无副作用
稳定——不会因无关更改而失败（避免行计数检查，匹配模式而非位置）
成功时静默——退出码0表示事实成立，非0表示不成立

有效的命令会检查具体、明确的内容：

undefined

Dependency exists in manifest

依赖项存在于清单中

grep -q '^clap' Cargo.toml grep -q '"express"' package.json

File or directory exists

文件或目录存在

test -f tests/cli.rs test -d src/components

A specific value or setting in config

配置中的特定值或设置

jq -e '.scripts.test' package.json >/dev/null grep -q 'edition = "2024"' Cargo.toml

Build or test suite passes

构建或测试套件通过

cargo build --quiet 2>/dev/null npm test --silent

A property holds (or does not hold) across the codebase

代码库中存在（或不存在）某项属性

! grep -rq 'unsafe' src/ ! grep -rq 'unwrap()' src/handlers/

Count-based invariants (use ranges, not exact numbers)

基于计数的不变量（使用范围而非精确数字）

test $(find src -name '*.rs' | wc -l) -ge 10

Behavioral test — actually exercise the tool

行为测试——实际运行工具

facts list --help 2>&1 | grep -q '--section' echo '- test fact' | facts lint /dev/stdin 2>/dev/null

undefined

facts list --help 2>&1 | grep -q '--section' echo '- test fact' | facts lint /dev/stdin 2>/dev/null

undefined

What makes a command useless

无效命令的特征

The most common failure mode is keyword grepping: picking a word from the fact label and checking that it appears somewhere in a source file. This doesn't validate the fact — it validates that the codebase uses similar vocabulary.

undefined

最常见的问题是关键词 grep：从事实标签中选取一个词，检查它是否出现在某个源文件中。这并不能验证事实——只能验证代码库使用了相似的词汇。

undefined

BAD: "heading depth maps to hierarchy"

错误示例：“标题深度映射到层级结构”

grep -q "depth" src/parser.rs

This checks that the word "depth" appears in the file. It would pass

此命令仅检查“depth”一词是否出现在文件中。即使深度处理完全失效，它仍会通过。如果有人将变量重命名为“level”但行为未变，它会失败。

even if depth handling was completely broken. It would fail if someone

错误示例：“标签是用于筛选和分类的自由格式令牌”

renamed the variable to "level" even though the behavior is unchanged.

—

BAD: "tags are freeform tokens for filtering and categorisation"

—

grep -q "tags" src/model.rs

The word "tags" will always be in a file that deals with tags.

处理标签的文件中必然会出现“tags”一词。这无法说明标签是否为自由格式或用于筛选。

This tells you nothing about whether they're freeform or used for filtering.

错误示例：“命令按顺序运行”

BAD: "commands run sequentially"

—

! grep -q "async|tokio" src/check.rs

Absence of async doesn't prove sequential execution — there are other

不存在异步代码并不证明是顺序执行——还有其他并发运行的方式。即使有人通过std::thread添加了并行处理，此命令仍会通过。

ways to run things concurrently. And this would still pass if someone

错误示例：“CLI将章节视为一等公民”

added parallelism via std::thread.

—

BAD: "the CLI treats sections as first-class citizens"

—

grep -q "section" src/list.rs

What does this even check? That the word "section" appears? Of course it does.

这到底在检查什么？只是“section”一词是否出现？它当然会出现。


The pattern to watch for: if your command is `grep -q "<keyword from the fact>" <file that obviously contains that keyword>`, it's not a real check. Stop and either find a meaningful command or leave the fact manual.


需要注意的模式：如果你的命令是`grep -q "<事实中的关键词>" <显然包含该关键词的文件>`，那么这不是有效的检查。请停止并寻找有意义的命令，或保持事实为手动维护状态。

When to leave facts manual

何时保持事实为手动维护状态

Not every fact can or should have a command. Leave facts manual when they are:

Subjective or qualitative — "extreme simplicity", "codebase is DRY", "polished UX"
About human processes — "bump version, commit, push"
About external systems you can't query locally
About behavior that would require a complex integration test to verify and is already covered by the project's test suite
About design intent — "each fact is atomic and independent", "file order is canonical"
Only checkable via keyword grep — if the only command you can write checks for a keyword rather than the actual claim, leave it manual

A fact sheet with 30 genuinely validated facts and 20 honest manual facts is far more useful than one with 50 commands that are all

grep -q "<word>" <file>

并非所有事实都能或应该添加命令。在以下情况下，保持事实为手动维护状态：

主观或定性描述——“极致简洁”、“代码库遵循DRY原则”、“用户体验流畅”
关于人工流程——“升级版本、提交、推送”
关于无法本地查询的外部系统
关于需要复杂集成测试才能验证且已被项目测试套件覆盖的行为
关于设计意图——“每个事实都是原子且独立的”、“文件顺序是规范的”
只能通过关键词grep检查——如果能编写的唯一命令只是检查关键词而非实际声明，则保持手动维护

包含30个真正经过验证的事实和20个诚实的手动事实的事实表，远比对50个命令全是

grep -q "<单词>" <文件>

的事实表有用。

4. Add missing facts

4. 添加缺失的事实

Identify important behaviors and features not yet captured. Prioritize in this order:

User-facing behaviors — what can someone do with this project? What happens when they do it? What happens when they do it wrong?
Contracts between components — how do modules communicate? What does each one promise to the others?
Edge cases and error handling — what breaks, how, and what does the user see?
Structural/architectural facts — only when they constrain behavior (e.g. "single-threaded, so handlers cannot block" matters; "uses the clap crate" rarely does)

undefined

识别尚未被捕获的重要行为和功能。按以下优先级排序：

用户面向的行为——用户可以用此项目做什么？执行操作后会发生什么？操作错误时会发生什么？
组件间的契约——模块如何通信？每个模块对其他模块做出了什么承诺？
边缘情况和错误处理——什么会出错，如何出错，用户会看到什么？
结构/架构事实——仅当它们会约束行为时（例如：“单线程，因此处理程序不能阻塞”很重要；“使用clap库”通常不重要）

undefined

Good — captures behavior a rewrite must preserve

良好示例——捕获重写时必须保留的行为

facts add "uploading a file larger than 10MB returns 413 with a human-readable error" --section api/upload facts add "duplicate messages within the 5-minute dedup window are silently dropped; the first is kept" --section processing/dedup facts add "when the database is unreachable, queued writes retry 3 times with exponential backoff" --section resilience

facts add "上传超过10MB的文件会返回413状态码和易读的错误信息" --section api/upload facts add "5分钟去重窗口内的重复消息会被静默丢弃；保留第一条消息" --section processing/dedup facts add "当数据库不可达时，排队的写入操作会以指数退避策略重试3次" --section resilience

Bad — structural trivia that wastes space and tells an agent nothing useful

不良示例——浪费空间且无法为代理提供有用信息的结构细节

facts add "the project uses PostgreSQL for persistence" --section architecture facts add "tests are in the tests/ directory" facts add "the CLI is written in Rust"


Prefer facts that are:
- **Behavioral** — describes what happens, not what exists
- **Atomic** — one truth per fact
- **Falsifiable** — you could imagine a broken implementation where this fact would not hold
- **Worth preserving** — if someone rewrote this project from scratch using only the fact sheet, would this fact help them get the behavior right?

A fact sheet with 40 precise behavioral facts is more useful than one with 200 structural observations. If your fact sheet is growing past ~80 facts in a single file, split into focused files (`api.facts`, `cli.facts`) and prune structural filler.

When writing new facts, use the entity names from the `## domain` section. Consistent vocabulary across the fact sheet helps agents build an accurate mental model. If you find yourself using a term that does not appear in `## domain`, either add it there first or use the existing term instead.

facts add "项目使用PostgreSQL进行持久化存储" --section architecture facts add "测试用例位于tests/目录中" facts add "CLI使用Rust编写"


优先选择以下类型的事实：
- **行为化**——描述发生的事情，而非存在的事物
- **原子化**——每个事实仅包含一个真实信息
- **可证伪**——可以想象一个失效的实现会导致此事实不成立
- **值得保留**——如果有人仅使用事实表重写此项目，此事实是否能帮助他们实现正确的行为？

包含40个精确行为事实的事实表，比包含200个结构观察结果的事实表更有用。如果单个文件中的事实数量超过约80个，请将其拆分为聚焦的文件（如`api.facts`、`cli.facts`）并移除结构细节类的冗余内容。

编写新事实时，使用`## domain`章节中的实体名称。事实表中一致的词汇有助于代理构建准确的认知模型。如果发现自己使用的术语未出现在`## domain`章节中，请先将其添加到领域章节，或改用现有术语。

5. Organize

5. 组织事实

Group related facts into sections using

--section

. Section paths support nesting (e.g.

api/auth

cli/subcommands

). Keep sections focused — split broad ones.

使用

--section

将相关事实分组到章节中。章节路径支持嵌套（如

api/auth

、

cli/subcommands

）。保持章节聚焦——拆分过于宽泛的章节。

6. Validate and report

6. 验证并报告

Run

facts check

to confirm all command-facts pass (this also lints the files).

Report what changed: facts added, edited, removed, commands added. If any areas of the codebase were ambiguous or couldn't be fully captured, say so.

运行

facts check

确认所有带命令的事实都通过验证（此命令还会检查文件格式）。

报告更改内容：添加、编辑、移除的事实，以及添加的命令。如果代码库的某些区域存在歧义或无法完全捕获，请说明。

Guidelines

指南

Keep fact labels concise and declarative.
Command quality matters more than command count. A command that doesn't actually test the fact is worse than no command — it creates false confidence. Only add commands that would break if the fact became false.
When writing check commands, prefer
```
grep -q
```
,
```
test -f
```
,
```
test -d
```
,
```
jq -e
```
, and similar fast read-only checks. Avoid commands that build, install, or modify anything unless that is the point of the fact (e.g. "project builds successfully").
Use tags to categorize when useful (e.g.
```
@ci
```
,
```
@api
```
,
```
@core
```
). Use
```
--add-tag
```
and
```
--remove-tag
```
for incremental tag changes.
Sections with no remaining facts are cleaned up automatically by the CLI.
Lifecycle classification is the primary job. Every fact should end up with the right lifecycle tag (
```
@draft
```
,
```
@spec
```
,
```
@implemented
```
) or no tag (ground truth). Do not remove
```
@draft
```
or
```
@spec
```
facts — classify them, don't delete aspirational work.
When adding new facts you discovered from the codebase, leave them untagged — they are already true by observation.
Behavioral facts over structural ones. When choosing what to add, ask: "would an agent reimplementing this project need to know this to get the behavior right?" File existence and dependency names are in the manifest. Deduplication logic, error responses, retry semantics, and edge cases are the things that get silently dropped in a rewrite — those are the facts worth writing.
Establish vocabulary before writing facts. The
```
## domain
```
section defines the project's key entities and relations. Use those names consistently throughout the fact sheet. If you find yourself using a new term that does not appear in
```
## domain
```
, either add it there or use the existing term instead.

保持事实标签简洁且具有声明性。
命令质量比数量更重要。无法真正验证事实的命令比没有命令更糟糕——它会带来虚假的信心。仅添加当事实不再真实时会失败的命令。
编写检查命令时，优先使用
```
grep -q
```
、
```
test -f
```
、
```
test -d
```
、
```
jq -e
```
等快速只读检查。除非事实的核心是构建、安装或修改操作（例如：“项目构建成功”），否则避免使用此类命令。
必要时使用标签进行分类（如
```
@ci
```
、
```
@api
```
、
```
@core
```
）。使用
```
--add-tag
```
和
```
--remove-tag
```
进行增量标签更改。
CLI会自动清理没有剩余事实的章节。
生命周期分类是核心任务。每个事实最终都应带有正确的生命周期标签（
```
@draft
```
、
```
@spec
```
、
```
@implemented
```
）或无标签（基本事实）。不要删除
```
@draft
```
或
```
@spec
```
事实——对其进行分类，不要删除有前瞻性的工作。
添加从代码库中发现的新事实时，不要标记——它们已通过观察证实为真。
优先选择行为事实而非结构事实。选择添加内容时，请思考：“重新实现此项目的代理是否需要知道此信息才能实现正确的行为？”文件存在性和依赖项名称可在清单中找到。去重逻辑、错误响应、重试语义和边缘情况是重写时容易被忽略的内容——这些才是值得记录的事实。
编写事实前先确立词汇表。
```
## domain
```
章节定义了项目的核心实体和关系。在整个事实表中一致使用这些名称。如果发现自己使用的术语未出现在
```
## domain
```
章节中，请先将其添加到领域章节，或改用现有术语。

Example session

示例会话

undefined

undefined

Load current state

加载当前状态

facts list facts check

Spawn subagents to scan the codebase by feature area:

生成子代理按功能区域扫描代码库：

Subagent 1: user authentication — login, signup, session handling, token lifecycle

子代理1：用户认证——登录、注册、会话处理、令牌生命周期

Subagent 2: payment processing — charge flow, refunds, webhook handling, error cases

子代理2：支付处理——收费流程、退款、Webhook处理、错误场景

Subagent 3: notification system — delivery channels, retry logic, dedup, rate limits

子代理3：通知系统——交付渠道、重试逻辑、去重、速率限制

Build the project ontology from scan results:

根据扫描结果构建项目本体：

facts add "a PaymentIntent is a Stripe object representing a single charge attempt" --section domain facts add "a Webhook is an incoming HTTP POST from Stripe reporting a payment event" --section domain facts add "a DeadLetter is a Webhook that exhausted all retry attempts" --section domain facts add "a Session is a server-side auth record tied to a refresh token" --section domain facts add "a PaymentIntent produces Webhooks on status changes" --section domain facts add "failed Webhooks become DeadLetters after 3 retries" --section domain

Classify existing facts by lifecycle stage (using domain vocabulary):

按生命周期阶段分类现有事实（使用领域词汇）：

This fact is true — code proves it

此事实为真——代码可证明

facts edit x1z --add-tag "implemented"

This fact is precise but the code doesn't exist yet

此事实精确但代码尚未实现

facts edit a2b --add-tag "spec"

This fact is vague ("supports payments") — needs refinement

此事实模糊（“支持支付”）——需要细化

facts edit c3d --add-tag "draft"

An old fact about Python is no longer true — project migrated to Rust

关于Python的旧事实不再成立——项目已迁移到Rust

facts remove p2q

Found behavioral truths while reading code — add untagged (ground truth)

阅读代码时发现的行为真相——添加无标签（基本事实）

facts add "failed payment webhooks retry 3 times with exponential backoff, then dead-letter"
--section payments/webhooks facts add "API rate limits to 100 req/min per key; exceeded requests get 429 with Retry-After header"
--section api/limits

Verify everything

验证所有内容

facts check

Report: 6 domain facts added, 5 classified (@implemented: 3, @spec: 1, @draft: 1), 1 added, 1 removed

报告：添加6个领域事实，5个事实完成分类（@implemented:3，@spec:1，@draft:1），添加1个事实，移除1个事实

undefined

undefined