跳到主要内容

Reader Surface Cleanup SOP

状态: Active SOP / R3 Lane L9 产出 最后更新: 2026-05-15 适用范围: 任何在 projects/<proj>/、baseline/、contexts/、evaluation/<proj>/ 下的 canonical / support 类正文文档 触发根因: FR-011（叙事被 process metadata 污染）+ Codex Reader Audit P1 finding（"reader-surface 首屏全是项目演化叙事，新读者第 0-30 行无法判断'本文档要回答什么'"）+ Cursor Self-Audit RC-A（作者无法是自己的 reader）

本 SOP 不修改任何文档。它定义"首屏 30 行应该是什么、不应该是什么"，由各 project Controller 在自己的项目领域内按 SOP 自行清洗，遵守 FR-010 边界（Admin 不直接改项目级 canonical 内容）。

1. 为什么需要这份 SOP​

三方 audit 一致发现：

  • 多份 canonical 文档（FinClaw 的 strategic-whitepaper.md / product-definition.md / mvp-product-definition.md 是最典型样本）的前 30 行充满了 "本文档不是 X" / "2026-05-XX 更新说明：..." / 已吸收议题列表 / pattern-provenance 注释 / 6+ 行元数据列表 等"作者自述演化历史"信息。
  • 这些信息对已经在跟踪文档演化的作者有价值，但对首次进入文档的新读者 / Agent而言，30 行内没有得到"这个文档要回答什么、什么时候用、读完能做什么" 的答案。
  • 这正是 RC-A "作者无法是自己的 reader" 的具体表现：作者觉得"演化说明很重要要放在前面"，但 reader 视角下"前 30 行应该回答 What/When/Outcome"。

2. 首屏 30 行必须包含的 4 件事​

顺序内容字数预算形式
1What —— 这个文档定义/约束/记录的是什么1 行一句陈述句
2For whom + When —— 谁在什么任务下应该读这份文档1-2 行"如果你是 X、你正在做 Y，先读这份"
3Outcome —— 读完这 N 分钟后读者能产出什么1 行"读完后你能 ..."
4Trust level —— canonical / support / evidence + 当前是否处于 active 维护1 行直接给 governance taxonomy 标签 + 状态

合计 首屏前 5-7 行解决 What/Who/When/Outcome/Trust，剩余 23-25 行可以放：

  • 1 行最后更新日期；
  • 1 行上游 / 下游链接（最多 3 个）；
  • 跳跃式目录（progressive disclosure 锚点）；
  • 一段最短的"开篇正文"（不超过 5 行，直接进入主题）。

3. 首屏 30 行不应该包含的内容​

以下条目按 audit 频次降序排列：

  1. <!-- pattern-provenance: ... --> 注释：移到文档末尾或单独的 meta/ 目录；不在首屏。
  2. "本文档不是 X / 不是 Y"的边界澄清：移到 §1 或 §2 内的"边界"小节；不放首屏。
  3. "2026-XX-XX 更新说明：本文档已吸收 ... 议题"：移到文档末尾的"演化记录 / Changelog"；不放首屏。
  4. "上游来源 / 来源材料 / 设计支撑"5+ 行链接列表：合并成 1 行 "上游: A → B → 本文; 下游: C, D"；多余链接进入正文具体段落。
  5. "15 项原始议题中编号 14 缺失"等执行过程注释：移到 sync packet 或 evidence 文件；不属于 canonical 首屏。
  6. "项目"/"文档级别"/"状态"等 6 行元数据竖排：合并到 trust level 那 1 行，或迁到文末元数据块。
  7. 任何对内部讨论流程的引用（"经 2026-05-12 多轮讨论收束"）：移到 changelog 或 sync packet。

4. SOP 操作步骤（每份文档 ≤ 15 分钟）​

  1. 截屏当前首屏: 把文档前 30 行复制到笔记，标注每行属于"What/Who/When/Outcome/Trust" 还是"演化叙事/边界澄清/元数据"。
  2. 测算占比: 演化叙事 + 元数据若 ≥ 50%，需要清洗。
  3. 重写首屏 5-7 行: 严格按 §2 表格的 4 件事顺序写。
  4. 建立"演化记录"块: 在文档末尾加 ## Changelog / 演化记录 或 ## Meta / 元数据，把 §3 的 1-7 条全部移过去。
  5. 保留所有信息: SOP 是重排不删除——演化叙事不是错误，只是放错位置。
  6. Reader test 验收: 按 reader-testing-protocol.md §4 L1 强度，用 1 个独立 agent（Codex 或 OOSO）读首屏 30 行，问"这份文档解决什么问题、什么时候用、读完能做什么"，三个问题都答对算通过。

5. 何时不适用本 SOP​

  • controllers/<role>/state.md —— 这类文档首屏天然就是 Controller 状态元数据，不在 reader-surface 范围。
  • packets/sync/、packets/escalation/、packets/handoff/、packets/task/ —— packet 类文档的首屏由 packet schema 定义（YAML front-matter），不走本 SOP。
  • evidence/ —— evidence 类文档首屏可以是采集元数据（采集时间/方法/sandbox 限制），不需重排。
  • source/ —— 原始材料保留原貌，不清洗。

6. 与现有 governance 的关系​

7. 不在本 SOP 范围​

  • 不规范"文档应当多长 / 多深 / 多详细"；
  • 不规范"哪些 section 必须有"——那是 project-canonical-required-fields.md 的职责；
  • 不裁定"演化叙事 vs canonical 正文" 的优先级，只规范"它们的物理位置"；
  • 不强制每份文档都立即清洗——有 R3 优先批次（FinClaw 三份 canonical），其他文档 Controller 自行排期。

8. 首批适用样本（R3 P1 范围）​

  • projects/finclaw/strategic-whitepaper.md —— 首屏 ~17 行被演化叙事+元数据占满
  • projects/finclaw/product-definition.md —— 同上 + "议题编号 14 缺失"等执行过程注释
  • projects/finclaw/mvp-product-definition.md —— 同上 + "Controller 多轮讨论已收束"过程引用

清洗任务通过 packets/sync/labs-fintecai-finclaw-canonical-reader-surface-proposal-2026-05-15.md 提议给 FinClaw Controller，保留 FR-010 边界。