三思而后行 · 改前通读的自律流程
改任何已成形的文档之前,先看整体,再动手。软约束,不阻断交付,只挡在「要动手改」这个动作前面。
范围说明:本技能只管文档类产物(文章、调研、方案、技能文档等成形文字)的修改。代码/工程改动不在本技能范围,交给专门的验证流程,别在这里处理。
为什么单开这个技能
不替你写,只挡在修改动作前面。
文档、方案、技能文档这类成形的东西,都会犯同一个毛病:只盯局部,不看整体。这个毛病不属于任何一个具体产物,单开一个技能来管它。
它是前置动作,跟写作/改稿技能并行,不是二选一。 那些技能管怎么把内容写好,这个技能管的是动手之前先看整体骨架——判断这处怎么改才不破坏整体。它是底层能力,该跟具体的写作技能一起走,不占它们的名额。顺序是:先三思(看骨架、判断这处怎么改才不破坏整体),再动手写/改。别因为一句话里带了"润色""精简",就只想着动笔、把这一步跳了。
触发场景(反模式清单)
命中任一即启动:
- 评审 / 反馈意见指出文档某处有问题,准备直接冲上去改那一处,没回头看全文。
- 用户说「改一下」「加一段」「顺手改一下」「只改这一处」「补一下」「快速改一下」。
- 用户说「润色一下」「精简一下」「优化下措辞」「压缩这段」「扩写一下」「顺一顺」——文字加工也是改已有内容,先看这段在骨架里的位置再动。
- 用户丢一整篇文章说「优化一下」「通篇顺一顺」,没指改哪儿——别逐句润色,先抽骨架,自己找出承接断了、论据放错节、结论收不全的地方(细则见
doc-scope.md)。 - 新增一段内容 / 一节章节,准备挂在已有文档末尾。
- 改文档的一节,没重读其他章节。
- 处理别人对文档的评审意见,准备逐条改,不看全文骨架。
- 迭代 / 更新一个已有技能文档、方案、配置说明。
不触发:从零新起一篇(没有既有骨架可通读)、纯一句话答疑、明确说"随手写个一次性草稿"。
「整体」怎么定义(按载体分)
不同载体,「整体」落到不同东西上:
| 载体 | 「整体」指什么 | 通读到什么程度 |
|---|---|---|
| 文档 · 修改一处 | 全文骨架 + 前后章节的承启 | 知道这一处在骨架里的位置、上一段收在哪、下一段起在哪 |
| 文档 · 通篇优化(没指改哪儿) | 全文骨架 + 论据归位 + 结论闭合 | 抽出主干,自己找出哪几节承接断了、论据放错了、结论收不全(细则见 doc-scope.md) |
| 文档 · 新增一节 | 全文骨架 + 主线 | 新节能不能顺进骨架,顺不进去要么调骨架,要么不加(细则见 doc-scope.md) |
| 技能文档更新 | SKILL.md 主体 + 所有 references + 已发布版本 frontmatter | 找到本次改动的既有依据,不叠加平行防线;不覆盖已定的 description |
| 方案/配置说明 | 完整方案/配置文件 + 上游被谁引用 | 改一处能说出谁会受影响 |
三步硬约束(改前必走)
底子是三条业界经典:Shotgun Surgery(改一处要连带看多处)、Chesterton's Fence(拆之前先搞清它为什么在)、Outline-First(骨架先立)。源头见 references/prior-art.md。
通读整体
按上表读到位。不到位不许下笔。
- 文档:通读全文,列出骨架(一节一句话观点)。
- 技能文档:读 SKILL.md 主体 + 所有 references。
- 方案:读完整方案。
列影响面
两栏,写下来(重档)或口头说清(中轻档):
- 这次要动的点:准备改/新增的具体位置。
- 跟这个点相关的既有逻辑:文档骨架里的前后章、已有的类似论述、依赖此处的下游章节。
相关的没列全,不许下笔。
三问过闸
一条一条问,一条不过就停:
- 这个点,全文 / 技能历史 / 方案版本里之前动过吗? 动过就先看历史,别把上次刚删的加回来,别推翻上一次评审已经定的事(对应 Chesterton's Fence)。
- 修法的风险比原问题大吗? 大就换修法,别硬扛(对应 Band-Aid 反模式)。
- 改这一处,会不会破坏整体骨架的连贯? 破坏就回骨架重来,不许硬插(对应 Shotgun Surgery)。
三问任一不过,回退到「不改」或「重设计」,不许硬修。
骨架优先(文档场景专用规矩)
新写和大改文档时,单独一条硬约束:骨架先立,内容后填,过渡最后加(对应 Outline-First):
- 先列骨架:每一节一句话观点,顺一遍能不能立住、之间有没有承启。
- 骨架顺了,再填内容:每一节内容展开。
- 最后加过渡:章节之间的承启句,让整篇喘得上气。
- 改了任何一节,回骨架重扫一遍:骨架被破坏了就重来,不许打补丁维持假连贯。
产出:改前通读报告
三步都过完,给一份报告(中重档写下来,轻档在心里过并口头说):
【改前通读报告】 ## 通读了什么 - 载体:文档 / 技能文档 / 方案 - 读的范围:...(具体到文件、章节) - 读到什么程度:... ## 影响面清单 - 这次要动的点:第 N 节「XX」 - 跟这个点相关的既有逻辑: - [章节/位置]:... - [章节/位置]:... ## 三问回答 1. 这个点历史上动过吗? → 未动过 / 动过:[章节 / 版本],历史结论是「...」 2. 修法风险比原问题大吗? → 不大,理由:... / 大,换修法:... 3. 会破坏整体骨架吗? → 不破坏,理由:... / 破坏,决定回骨架:... ## 决定 - [ ] 改(按上面结论动手) - [ ] 不改(理由:原有机制能兜住 / 修法风险大) - [ ] 回骨架重设计(理由:硬插会破坏一致性)
三问任一不过,给「不改」或「回骨架」,不许硬修。
反模式硬禁止
- 「先改上再说,以后统一整理」:补丁摞补丁的入口,禁止。
- 「小问题快速改一下,不用看那么多」:「小」和「快」是补丁的两个借口,不成立。
- 「只改这一处,不动其他的」:不看整体就不知道要不要动其他。
- 「说优化就逐句润色」:没指改哪儿时只抠措辞,论据放错节、结论收不全这类骨架病全漏掉。先抽骨架再动。
- 「新增的挂在末尾,不影响原文」:挂在末尾也是骨架的一部分,不融就是补丁。
- 「上次刚删的又加回来」:文档 / 版本历史都不看,禁止。
- 「一遍改一遍看效果,来回反复」:是没通读整体的症状,回第一步。
力度与豁免
软约束,不阻断交付:
- 重档(对外文档 / 已发布技能文档更新):三步全跑,报告写下来。
- 中档(内部文档修改 / 手记类):三步跑,报告口头说清。
- 轻档(拼写、typo、格式微调、明显笔误):可跳过,但要在心里过一遍,这真的只是 typo 吗?
豁免:一次性丢弃的草稿、纯一句话答疑,可以跳过。豁免要在心里对自己说一句「这是草稿,不是产出」,能说出口才算数。
出稿前自检
- 通读做到位了吗?(文档通读全文了吗?技能看了所有 references 吗?)
- 影响面清单列全了吗?
- 三问答完了吗?任一"不过"有没有硬修?
- 有没有踩到"上次已删的又加回来"这条?
- 骨架还立得住吗?
任一答不上,回去补。软约束不是可跳过,是"跑不过不阻断,但要显式说出豁免理由"。
