Tighten Doc

tighten-doc — 文档写作与优化

Use this as the default document finalization and editing skill; new-substance authoring routes to the owner skill first. A deliverable doc is written for its reader (product / business / exec / teammate), not for the author. Default form = one-page operational/task manual: few short headings, enumerations as tables/bullets (one point per line), short sentences, no bracket piles, no template scaffolding.

When to use

Use any time you rewrite, tighten, polish, or finalize a doc someone else must read, after owner and scope are clear: strategy, plan, spec, task card, runbook, release note, or collaborative doc.

Three modes:

• Draft: after the owner skill has settled the substance, turn rough intent, notes, meeting output, or task context into a readable first version. Route to an owner when substance is unsettled and the type matches an installed owner skill: spec/standards/guideline -> product-rd-workflow, test cases -> test-artifact-management, architecture -> architecture skill, code/correctness -> stack/review skill. For new standards/spec authoring, product-rd-workflow is the single entry; the hand-back marker is product-rd owner-ready with authority statement, doc-family layer, and enumeration evidence — after that, finish wording here. If that marker is absent for a standards/spec artifact, polish only locally and mark pre-owner blocked (share/publish gate below). Standalone non-spec artifacts without family references skip it. If no owner skill is installed or reachable, draft from the charter plus user/session-supplied substance — never invent substantive decisions; they stay owner/user-provided. 多轮文档先锁 charter：references/doc-charter-first.md
• Rewrite: restructure an existing doc so decisions, owners, gates, and next actions are easier to scan.
• Tighten: remove filler, duplication, AI tone, meta narration, and over-long sentences without deleting decisions.

For a technical / developer-facing doc, classify its reader-mode — the four Diataxis documentation modes: tutorial (learning by doing), how-to (recipe for one task), reference (look up exact facts), explanation (understand why). Keep one dominant mode per doc and watch for a muddled purpose — a doc trying to be a full tutorial and a full reference at once serves neither reader; that is the failure, not a compact options/env table inside an otherwise how-to doc. Use the four modes as a guide to spot muddle, not a top-down plan that forces four separate docs. The one-page operational-manual default above is the how-to / reference shape; a tutorial or explanation doc legitimately differs, so don't force it into that shape. This stays within finalization scope: flag a reader-mode split candidate, but do not create, split, or reorder sibling docs, nor route doc generation, before the substantive owner settles the doc set (product-rd-workflow for spec/standards/guideline families, per its owner-ready gate) — a doc-generation skill is executor-only, never an owner replacement.

For spec/standard/guideline artifacts, the pre-owner blocked marker rule applies to all three modes — do not share/publish until the owner marker exists; local wording polish must preserve the blocked label.

Before sharing, syncing, committing, or publishing a concrete deliverable artifact, run Tighten mode by default. Do not ask the user whether to optimize unless the edit would change a substantive decision, remove required detail, or risk collaborative-comment loss. A request to write a template, SOP, report, checklist, Feishu/Lark doc, task card, or launch material already includes the optimization pass after the owner skill has settled the substance.

After multi-round edits that added, restructured, or changed reader-facing prose or meaning, always run the Tighten mode before sharing or publishing; rounds of only exempt trivial edits (typo/link/format) may record that exemption instead. What counts as evidence for this pass: re-read the affected deliverable surface against the rubric (duplication — including same-content-different-face introduced by your own earlier edits in the same session — 一坨, term drift, cell-fits-column) and record: the surface, the touched blocks since the last full pass (the minimum index of scope, not the ceiling — include sections whose meaning the edits change), whether a full-card / family-wide sweep trigger below applies, the defects found or an explicit none, and the reason if scope stops at the touched blocks. Per-edit rubric compliance while writing, grep-only closeout scans (halfwidth / residual-wording checks), or a substance review do not substitute, singly or jointly — the recurring miss is accepting them as equivalent evidence and shipping a self-introduced duplication the surface re-read would have caught.

技术 / 参考文档：form 优化 ≠ 内容已核。 当本轮新增 / 改写 / 发布了可对源码核验的承载性技术断言（API 签名、env 行为 / 优先级、字段 / label 名、默认值——这类文档常自述真值源），且一手源用户已给、在当前工作区可得、或用户明确授权查证时，form 清理之外要把这些断言对一手源码（SDK / specs / fixtures / 可跑命令）核一遍。核出不符：仅 source-literal 的 typo / 名称 / 默认值笔误可直接照证据改；会改动 substantive contract / decision 的只标 discrepancy / pending 交 owner（stack / review skill），tighten-doc 不接管纠错。源不可得、超出本轮范围、或只是轻量润色：只做 form 并声明「形式已优化、内容未核」，不得裸称「文档已优化 / 准确」（别把每次 tighten 滚成一次代码审计）。

DELETE (废话 — cut these)

1. 元语自证 / doc-about-itself: "这是X不是Y文档", "本文档/本卡…", "读者是…", "别写空话". 最高频的 agent 自插入形态：给自己新写的段落加的向导式 opener/closer —— "本节只做X", "本页/这里不维护Y", "这张表只是…", "执行时不要只按本页…", 以及自述用途的引用开场（"用于配套《X》…放引用链接"）。读着像帮读者，其实是 元语自证 + 废话；删掉让内容自己站住。发布任何你自己写的段落前，先扫它的开场/收尾句是否是这一类——这正是"我把信息写对了"之后还残留、要读者来挑的废话。（承载真实决策/边界/受众约束/例外/后果的开场不算，删的是只描述"本节存在/本节是什么"的句子。）
2. 翻旧账 / blame: "没人跟全空", "证据：…当初也写过".
3. 修辞尾巴 / 口号 used as a closer: "…= 没解决", "做得再全也…", "上线≠X" as a rallying shout.
4. 无动作语气词: "周会点名" (doesn't say who / when / what) — replace with the real mechanism.
5. 无谓条件前缀 / 连接: "…时", "节奏跑不动时", "总之", "换句话说", "值得一提的是".
6. 重复: a heading restating the table's column names; a clause duplicated in another section. Index docs especially: define each term/role exactly once — later sections reference, never re-explain. When a line is challenged, first check if its content already appears in another section; keep only the delta. Aggregation / cross-cut / "references" sections are the prime filler suspect (they compress per-card content into slash-soup that also duplicates the cards) — collapse to a plain short gate list or delete.

近义词斜杠堆 = 重复：一行里 A/B/C 若各词同指一件事，收成 1 个代表词；各项确为不同事才留斜杠列表。逻辑子集措辞 = 表面冗余：并列两项中一项是另一项子集时读着冗余——删子集项，或点名两个不同失效机制让区分显式。跨节正反复述 = 隐蔽 dup：同一组判据被一节正面写（"满足 A+B = 通过"），另一节反面 / 否决形式重写（"反面 ¬A / ¬B 任一成立 = 不通过"）——内核同一份内容、换面孔。审查主动配对扫：每个"判定为 Y"句的 criteria 在别处是否以"否决 / 反证 / 不通过"形式重列；命中 pick 一处保留（通常留反向 / 否决列表，更直接 checkable），另处删。这类 dup 在"已清"二审里最易漏过，是 R1 review-completeness 的重点 watch。 图↔文字双写 = 重复：图承载流程 / 连线 / 状态迁移，文字别逐条复述。但文字要保留图说不清或不能丢的执行信息——判据 / 为什么 / 例外 / owner / 硬规则 / 阈值 / 后果 / 验收 / 非渲染 fallback（即 KEEP 项一律留，别当"复述图"删掉）。 加图 / 表后必做配对扫（加图时最常自引入的 dup）：是找 delete candidate 不是命中即删——只删纯步骤 / 节点复述；查的范围覆盖图所在小节 + 相邻小节 + 验收 / 红线段，不只邻近 bullet。 Row-granularity in an index/owner/lane table: one row per domain/lane. A row that is actually a sub-component of another row's domain (e.g. an SDK or a gateway sub-piece listed beside whole domains) → merge it into the parent row (fold its owner/progress/goal in), renumber, update the heading count. Do NOT merge two rows with distinct owners or timelines — that loses accountability; an owner-justified split stays.

1. 病句 / bulk-replace artifacts: e.g. "一键回退排障手册" (missing separator).
2. 自造版本号或前缀: never invent "v7 战略文档" — verify the real title first; a _v1 filename ≠ the doc title.
3. 编辑性括号副标题: "（按对的赌注不折中）", "（诚实校准）", "（怎么算通过）", "（含…前置底座）".
4. 画蛇添足的解释尾: "中途不换手", "（DoD）" tacked onto an already-clear line.
5. 假目标: a 目标/DoD cell that is a bare verb with no object or threshold ("V1 修完 + V2 决议", "止血/打通/完善", "韧性补齐"). Not filler-to-delete but filler-to-fix → rewrite as a falsifiable DoD traced to the owning card (never invent a threshold); if the real DoD lives in that card, replace with the pointer "见〔X 域卡〕". If the cell references an undefined term (e.g. "V2"), trace it to its definition point and either inline-gloss it once so the cell is self-explanatory, or point to the card — a reader having to ask "X 是啥" means the cell failed.
6. 会话视角泄漏：句子立足于写作会话而非文档；必须先读 references/session-vantage-leakage.md，逐项走完 8 类：死会话 / PR-stack / 变更史与无锚点 / 评审编排 / 辩护 / 推导账 / hedge / 工作语言；HEAD-reader 可解？存事实、删过程；勿删稳定版本、issue、抑制理由、反事实钉、实测。

KEEP (实质 — NOT filler; deleting them drops a decision)

owner · 硬规则 · 完成标准/DoD · 里程碑 · 数值阈值 · the real build-vs-buy decision · severity/consequence rationale ("=资损法律风险 / =假安全 / =刑责风险 / 损失大" — that IS the judgment, keep it). Word it as severity, never as "死". The consequence label is KEEP, but the word "死" (资损法律死/刑责死/信任死/组织死) is rejected — reword to 风险高 / 损失大 / 刑责风险 / 信任崩 / 组织级风险. ("死" only stays in its non-consequence senses: 死线=deadline, 死约束=hard constraint, 死信=dead-letter, 钉死/封死=lock, 生死=critical-emphasis.) Compression ≠ deleting decisions: before compressing, extract the decided-points checklist (目标 / owner / 硬规则 / 后果论据 / build-vs-buy / DoD / 里程碑 / 最小交付) and verify each survives the rewrite.

FORM

• Named hyperlinks, never bare URLs: [真实文档名](url). Verify the real title before naming a reference; don't fabricate version prefixes.
• Collaborative docs that support rich structure (Feishu/Lark Docx/wiki, Confluence-like pages) should use the platform's rich-text structure when creating or materially rewriting a document: headings, tables, bullets, and named hyperlinks should be real document nodes, not plain Markdown pasted as body text. Use Markdown only when the target surface is Markdown-native or the user explicitly asks for it.
• In Feishu/Lark standards families, document references must be named hyperlinks, not quoted plain titles such as 《测试规范》. If a sibling doc is referenced more than once, verify the title once and reuse the same named link across the family.
• 断言写到证据等级为止。 交付文档里的结论按主张状态分「来源明确陈述 / 有证据支持的推论 / 作者判断」三态，不得混写成同一种口气；「来源明确陈述」是归因不是真实性——写成「来源 X 声称」，不得因有出处就用事实定论口气；作者判断句显式带「判断 / 预计 / 我认为」类标记，证据只到推论级就用分级句式写（如「机制可证、参数不可证」）。三态管解释性/推断性主张；直接观测豁免只限原始计数/测量值（如「本次查询返回 N 行」按本来面目写，不强套归因句式）——工具生成的分类/评分/裁决仍须标状态并写明工具权威边界。状态沿用实质 owner 或证据表已定的等级：润色时不得自行升降格；owner 未定状态的断言不改文、按既有通道标 discrepancy 交还 owner——已生效的决定、门槛、验收标准不因缺状态标签而被标「待确认」降级（调研类交付物的状态产出由 multi-perspective-research 合成简报持有，本条管所有交付文档的表达面）。
• 外部基线 / 标准值入文档 = 独立标注 + 命名来源 + 内部门（若有）仍权威。 引用外部 benchmark、行业阈值、标准默认值（评测目标、性能预算、参考 SLO 等）时，放成独立的列 / 行 / 标注并配命名来源超链，别和本系统自己的验收门 / 阈值混写成同一个数。当本系统有自己的验收门时显式声明本系统门为准、外部值只作对标参考（反模式：把外部基线直接当验收标准，读者误以为外部数就是上线门）；若文档本身即标准 / 评测报告 / 无内部门，则标清来源 / 范围 / 权威，别杜撰一个内部门。评自己的稿是这条的另一半：对自己产出的文档评可实测呈现属性（加粗密度、句长、结构层级）前，先建同体裁实测基准——长文或系列交付物在初稿前建（写完被纠正后再补测，是实测过的返工形态）——按预先声明的抽样框与纳排规则（在实测待评稿自身指标之前冻结，防止看完自己的数再挑参照系）取同体裁公开样本（记录样本量、口径与局限；不得挑对自己有利的样本充数，"若干份"本身不构成充分门槛），中英文样本分开统计，把待评稿放进分布里定位；找不到可靠公开样本或体裁不可比时如实记「未对标 + 原因」；流行排版阈值逐条核到一手出处再用，核不到不用。分布定位的合法输出是描述（"高于/低于所选样本分布"），不是裁决："合适"要再结合读者任务与可用性判断；"优于同类"不得由密度类粗指标推出；无基准时该属性只能报「未对标」——自己的审美不是分布。密度居中更推不出「稿子写得好」：整体质量仍按文档目的、读者任务、事实核验与本 rubric 分轴判断，呈现分布不背书内容正确性。
• No inline ｜ / pipe-delimited lists (RACI / 分工) — break into bullets or a table.
• Short sentences, one point per line, enumerations as tables.
• 表达形式匹配内容：分支关系 / 状态迁移复杂到文字难扫时优先图（mermaid 等）；字段对比、分桶属性、owner/gate/证据矩阵优先表；线性步骤用编号列表；一两点判断一句话或 bullet。别为单个判断加装饰性多桶图，但桶间有不同 owner / 阈值 / 例外 / 后果时必须结构化（该结构别压成一句）。目标环境不稳定渲染图时（邮件 / 终端 / 部分 Markdown），文字版流程为准、图只作辅助。callout / 图内文字 = 概览形态，只承一个要点：callout 塞成多点密块（"一坨"）就拆开或降到正文 / 表；图内边标签、节点名要短到不折行（长串在渲染端会断行错位）；承载性名称留全称、必要时短别名 + 图例，详情进正文别堆进图。
• 代码进代码块，不进段落：多行 / 独立执行步骤 / 长 flag 串命令 / 多命令序列放代码块（带 lang），不写成段落里的纯文本或一长串内联 code。短的随文 one-liner / 表达式、对照表单元格、「用 func()」式符号引用可留 inline，只要不长到影响扫读（与上面的表格单元格 / 内联引用规则一致，别硬塞进代码块）。多语言对照两端形态对齐——一端给了代码块，另一端别写成「Go：call(...)」式内联段落。
• Enumeration sections (依赖/兜底/分工/里程碑 子项) = multi-line sub-bullets, NOT a ；-collapsed single line. Readability beats compactness here; a - 依赖：A；B；C；D run is hard to scan — split to - 依赖： + one - A sub-bullet per item. Do not collapse to one ； line just for parity with another card; parity is not a reason to reduce scanability. Single-line ； is only for a true 2-item short pointer where sub-bullets would be heavier than the content.
• Table cells that list multiple skills, owners, checks, environments, or evidence items should be split into multiple lines or shorter rows. A readable table beats a compressed cell when the cell is used as an execution checklist.
• Terms unified and glossed once in a 白话 section (e.g. 红灯 = 卡住/NO-GO 到点必升级; 排障手册 = 排障 SOP). Also catch intra-doc term drift: the same concept written two different ways in one doc → align to that doc's prevailing term. Drift includes unit drift in a sequenced ladder (a milestone list mixing 第N周 and N天 — align the lone odd unit to the ladder's prevailing one).
• A column/section header must match what its cells actually hold (a "文档化进度" header over cells that hold 现状 is a defect — rename the header to the truth). An editorial paren in a header/heading that restates an intro rule is the same 编辑性括号 as DELETE #9 — cut it.
• Reader-facing published docs: the problem is unexplained or non-navigable internal references, not the names themselves. Fix three recurring reader-blockers: ① internal repo paths used as navigation (see README.md) a non-author can't follow → name the human destination or link the published doc; ② opaque internal gate/code labels (R0 / F4-style) → plain-name or drop the code; ③ unglossed in-house English / abbreviations (mTLS / PTY / SLO) → 中文化 or gloss at first use. Keep anything the reader actually operates on or that is a public convention / protocol / API / field / contract / standard name (AGENTS.md, CODEOWNERS, package.json, well-known abbrevs) — gloss if unfamiliar, don't delete.
• A cell must fit its column's semantic role. A 负责人/owner column entry must be a who (person/role), a 事项/规则 column a what (a parseable clause). Over-terse text — including a value the user dictated in an earlier pass — that no longer parses as that column's type ("业务真值+ 误差" in a 负责人 column; "…必需的指标建立" as a 规则 clause) is a 病句 (DELETE #7). On re-review, read each dictated/compressed value back in its column context, not in isolation; flag it with the rule even if the user set it (don't silently override, but don't pass it as clean either).
• Title altitude + doc-family prefix. A doc / section / reference title names the capability at goal-altitude — drop words the doc type already implies and any scope-enumeration that isn't doing distinguishing work (an SOP titled with its own gate-cases is usually over-long).
• Keep the capability plus whatever distinguisher(s) actually separate it from its siblings — a scope enumeration can itself be the load-bearing distinguisher, so cut by the test "does removing this still uniquely name the doc?", not by a fixed word budget.
• Same altitude rule as a 目标 cell, applied to titles.
• When docs genuinely form a set, align their titles to the family's shared prefix so they scan as a group; do not force a prefix onto a title that does not belong.
• Renaming then propagates per the family-wide label sweep in WORKFLOW: update every inbound reference label to the one canonical title and residual-scan the old title = 0; leftover ad-hoc short variants are cross-doc term drift.
• Doc-family structure before wording. When drafting or tightening a standards/guideline family with several stack, service, or repo docs, first identify the family shape: overview/index, product Spec authority, stack/service child docs, and repo-local execution docs. Tighten the overview/index for authority, ownership, links, and sync gates before polishing child docs; otherwise the leaf docs may read well while the system lacks a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccoalm
• Source: ccoalm/ccl-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.