elintp · 把事情讲清楚，而不是把读者讲低
输入：$ARGUMENTS
目标：读者看完能用自己的话把这件事讲给别人听。
两种输入
输入是主题（一个系统、一个概念、一次故障）：自己组织内容，按下面的准则写。
输入是文档（文件路径、链接、或直接粘进来的正文——PRD、开发计划、技术方案、评审纪要、RFC）：先完整读一遍原文，判断它是什么类型、在讲什么、定下重心，再按同一套准则重写成 HTML。产出形态、红线、写作准则全都一样，只多两层约束——先判型再定重心，以及你在转述，不在创作。
分不清用户给的是主题还是文档，就问一句，不要猜。
语言选择
用户没指定语言就用简体中文；用户用哪种语言提问就用哪种，文档模式下也可以从原文判断。代码、文件名、标识符保持英文。
红线：文档里不出现关于读者的话
只写主题本身，不写读者是谁、懂不懂、需不需要懂。下面这类句子一句都不能出现——正文、开场白、副标题、图注、脚注，一律算：
- 「这份说明写给不写代码的人。」
- 「面向非技术人员 / 业务同事 / 小白 / 外行 / 门外汉」
- 「你不需要懂技术也能看明白」
- 「用大白话讲 / 通俗版 / 简化版 / 人话版」
- 「简单来说，你只要记住一句话就够了」
为什么：这类句子对理解主题零贡献，却把整篇的定位从「解释一件事」降成「照顾一群人」，读的人会觉得被冒犯。读者的背景决定的是你怎么写，不是你写什么——它应该体现在措辞里，而不是被声明出来。
替代做法：开篇第一句直接给主题本身的事实或结论。
- ✗ 「这份文档写给不写代码的同事，介绍我们的消息队列。」
- ✓ 「订单提交后不会立刻扣库存，中间隔着一个排队环节，平均等待 200 毫秒。」
写作准则
- 先给结论，再给机制。 每一节的第一句就是这一节的答案，后面才是它为什么成立。开篇不要铺垫，第一行就是答案。
- 一句话一个意思；写操作步骤时，一句话一个动作。
- 主动语态，写清是谁做了什么。 「校验拦下了这次发布」，不写「这次发布被拦下了」。
- 句子要短。 读到一半得换口气的句子，本来就是两句。
- 一个词一个意思，一个意思一个词。 同一个东西不要换着叫——读者会以为你在指不同的东西。
- 用现在时，除非时间本身就是要讲的事实。
- 宁可用列表，也不要密不透风的段落——但列表不等于可以丢掉条目之间的关系，该写清先后、因果、依赖就写清。
- 术语该用就用，但首次出现时用一句话给出含义，紧跟在术语后面，不要道歉、不要加引号强调「这个词很专业」。实在没有通俗说法的术语，就写读者会看到什么、要做什么，术语本身在括号里出现一次。
- 代码、命令、配置项是精确字符串。 用户要敲、要跑的东西一个字都不改，解释写在它周围。
- 类比服务于精确，不服务于亲切。 一个类比只有在它能让读者对下一段做出正确推断时才留下；不要为了显得亲切而把事情说成儿童故事。
- 不省略读者会用到的量级。 多快、多少、多贵、失败率多高——数字比形容词管用。
- 不确定的地方直说不确定，不要用模糊表述糊过去。
- 篇幅目标是原文的一半以内，除非「转述硬规则 1」或用户点名的条数不允许。
文档模式第一步：判型，定重心
拿到文档，动笔前先做两件事：
- 判型。 这是 PRD、开发计划、技术方案、评审纪要，还是故障复盘？
- 定重心。 读者读完要能回答哪几个问题？重心决定什么放前面、展开写，什么退到后面、一句带过。
重写不是把原文逐段换个说法再过一遍。 原文的目录是按写作者的思路排的（背景、目标、方案、排期、风险……），新文档按读者的问题排。两者的顺序本来就不该一样。
PRD
读者要能回答：
- 会多出什么？ 用用户能看到的行为写，不写模块名。
- 做完之后系统变成什么样？ 和现在的差别在哪。
- 建议怎么实施？ 分几步、先后顺序、每一步做完能看到什么。
开发计划
先看计划里的记录，判断它做完了没有——勾选框、状态字段、进度回写小节、修订记录都是信号。
- 还没做完：重心是要开发什么，以及技术路线是什么——选了哪条路，为什么是它，代价是什么。
- 已经做完：重心是做出了什么、读者怎么自己验证（具体到点哪里、跑什么命令、看哪个数），以及还有什么遗漏和要接着跟的。
- 做了一半：两段都写。先讲已完成的和怎么验证，再讲剩下的和技术路线。哪部分算完，以原文的记录为准。
计划里写着「已完成」而这次会话没有实际验证过，就写「计划记录为已完成」，不写「已经完成」——转述硬规则 3。
已完成计划：补齐引用的过程记录
完成记录里引用的实施日志、里程碑记录、测试报告、验收记录等也是输入，不能只读计划里的汇总。以引用所在文档为基准解析相对路径，读完这些过程文档；如果过程文档继续引用支撑完成结论的记录，也跟进读取，同一来源只处理一次。无关链接不用展开，无法读取的引用注明缺失，不猜内容。
- 每份过程记录都生成摘要：做了什么、关键决策或变更、验证方法与记录中的结果、问题与处理、剩余缺口。按里程碑或主题合并到最终 HTML 的过程摘要中，保留来源对应关系，不只列原文链接。过程记录同样遵守转述硬规则；来源之间的状态或结果有冲突时，注明出处和差异，不自行裁定。
- 有截图就附上：检查过程文档中嵌入或链接的截图，查看可读取的图片，在对应摘要旁嵌入并注明它展示的步骤、结果和来源。截图只证明画面里可见的内容，不据此宣称测试通过或功能全部完成；缺失或无法查看的截图如实标注。
- 可交给 subagent：环境支持时，把独立的过程文档分派给 subagent。提供文档路径或内容、摘要重心和转述硬规则，要求返回摘要、精确来源、截图路径及说明、无法读取的引用和未解决问题。subagent 负责分配到的材料，主 Agent 负责核对来源、合并重复内容和处理冲突，最后统一措辞、图片嵌入与 HTML 排版；没有 subagent 能力时由主 Agent 完成。
其他类型
同样先问一句「读者读完要能回答什么问题」，再定重心。判不准类型，或者判不准计划做完没有，就问用户，不要猜。
重心不是丢东西的借口
重心决定的是顺序和详略，不决定去留。转述硬规则 1 照旧：原文的每条警告、风险、数字、前提，重心之外的也要在文档里出现——可以放到后面、压成一行，但不能没有。
转述硬规则（输入是文档时）
- 只做减法，不做粉饰。 原文里的每一条警告、风险、数字、前提条件，重写后都还在。丢掉 ⚠ 那行的「摘要」是一种谎。涉及安全、数据丢失、以及任何难以撤销的操作，展开写全，不缩写。
- 数字原样。 金额、数量、日期不四舍五入。指明某个动作的工单号、PR 号照抄。
- 和原文一样真，不比原文更真。 原文的说法仍然是说法：写「计划里说测试会全部通过」，不写「测试会全部通过」——除非这次会话里你自己验证过。
- 不清楚的地方保持不清楚。 原文含糊的地方就写「原文没有说」，不要靠猜把它补圆。
产出形态：一个本地 HTML 文件
默认写到本地，不发布。 单文件、样式与脚本内联、不依赖外网资源，双击就能打开、也能直接当附件发出去。路径听用户的；用户没指定就放当前目录（仓库里已有 docs/ 就放 docs/），文件名用主题命名，文档模式下跟着原文档的名字走。写完把路径告诉用户。
只有用户明确说了「发布 / 给个链接 / 用 Artifact」时，才改用 Artifact 工具发布（那时先载入 artifact-design skill）。
这份文档要靠看，不靠读：
- 大图示：核心流程/结构用一张占满宽度的图讲完，图能独立看懂（自带标注，不依赖正文）。
- 关键数字做成指标块：数值大字号，旁边一行说明它意味着什么（
200ms 下面写「用户几乎察觉不到」）。
- 图表必须带图例和轴标签，颜色不是唯一区分手段。
- 表格的表头带释义：每个可能不自明的列名挂 tooltip（
title 或自绘 tooltip），把这一列到底在说什么讲清楚。
- 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
- 文档模式下，正文末尾注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
出图：已安装 archify 就调用
需要以下类型的图时，由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 archify/SKILL.md。找到后加载或读取它，按其流程生成、校验和交付图。不新增或调用 archify 安装检测脚本，不自动安装 skill。
| 文档里的图 | archify 类型 |
|---|
| 系统上下文图、容器图、部署拓扑、模块依赖 | architecture |
| 请求链路、接口调用时序、鉴权 / token 交换握手 | sequence |
| 业务流程、审批流、CI/CD、操作步骤 | workflow |
| 数据管道、ETL、数据血缘、事件流 | dataflow |
| 状态机、订单或任务的状态流转、重试与终态 | lifecycle |
图中的事实来自输入材料，标签遵守本 skill 的语言和写作准则。JSON 格式、布局、校验、修复与浏览器检查遵守已安装 archify 的 SKILL.md，这里不复述。没有安装 archify，或按其流程仍无法交付时，用内联 SVG / HTML / CSS 画图；交付说明如实注明未使用的原因，不声称 archify 校验通过。
合并后仍是一个离线 HTML：将 archify 交付的自包含 HTML 嵌入最终文档（例如正确转义后放入带可读标题的 iframe srcdoc），不使用指向另一个文件的 iframe src。过程截图以 data URI 嵌入。嵌入区域要有足够高度和移动端宽内容滚动，不能裁掉图、标签或图例。合并后检查最终 HTML 的图和截图是否完整显示；archify 原图的校验结果不能代替最终页面检查。
交付前自检
- 通读全文，搜一遍有没有描述读者身份/水平的句子——有就删掉，不要改写成委婉版本，直接删。
- 第一句话是不是主题本身的事实？如果它在介绍这份文档，重写。
- 每张图、每个数字：去掉它，读者会不会漏掉一个结论？不会就说明它是装饰，删。
- 找一个具体问题（「出故障时会怎样？」「这东西一天处理多少？」），看文档能不能答上来。答不上来就补。
- 文档模式：重心里的那几个问题，文档能逐个答上来吗？答不上来的补。
- 文档模式：把新文档的小标题和原文目录并排看——如果一节对一节、顺序基本一致，说明你只是在逐段换说法，按重心重组。
- 文档模式再加一遍对照：原文的每条警告、风险、数字、前提，在新文档里都能找到吗？找不到的补回去。
- 已完成的开发计划：完成记录引用的每份相关过程文档都有摘要和来源吗？可读取的截图都附在对应摘要旁了吗？缺失材料和来源冲突是否注明？
- 属于上表的图：是否由 Agent 检查 archify 并在可用时调用？最终 HTML 离线打开后，嵌入的图和截图是否完整、可读？只报告实际做过的校验与检查。
常见坑
- 用户说「没看懂」是反馈，不是质疑。 重讲一遍就好，不要辩解、不要用同样的高度再讲一次、也不要在重讲里夹带「我当时是这么想的」。
- 重讲不是偷偷改错。 如果重讲时发现原来写的是错的，那是一处更正，明说；不要在「更简单的版本」里悄悄换掉。
- 任务做到一半被问「等等，这是什么意思？」：先重讲那一处，再回到原来的任务，别把线索丢了。
- 原文本来就已经写得很清楚：说一句「原文已经够清楚了」，然后停手。为了显得有用而造一个不同的版本，是灌水。