用途：撰写 Linear 工单或 Pull Request 描述，让非工程师在开头就能理解，工程师在结尾能据此实现或评审。工单与 PR 共用同一骨架和规则，区别仅在时态（工单用将来时提议，PR 用过去时报告）、末尾细节章节和发布方式。
核心规则是渐进披露：读者从零开始阅读，在到达自身深度时停止，且此时必须已获得实际价值，因此每节比上一节更技术化。文档必须独立自足，不引用其他工单、PR、ADR 编号或设计历史；兄弟工作按功能描述而非编号。仅两处例外：交付状态表可引用落地各部分的 PR 或子工单；PR 可在顶部或底部放一行 Closes ENG-1234 链接，但评审者无需打开它。
章节骨架：前三个标题必须逐字且按序——Why this matters (plain language)、Where this fits、What we're building（工单）/ What this changes（PR）。其后为更深的细节层，按相关性从高到低排列，无内容可删但不可重排。标题需一行说明变化与收益，以能力而非机制开头，PR 标题还须符合仓库提交约定。
细节章节包括：契约/细节（标识符、令牌形状、不变量、权限，用表格呈现密集事实）；工单的 How it's delivered（状态表，允许 ✅/⏳ 加链接，可选组件图）；PR 的 Review guide（文件/区域、变更、检查点，先列承载关键变更的文件，标注机械性改动）；安全/正确性保证（每条以加粗短语开头再给机制）；工单的 Done when（可观察的终端行为，含护栏场景）；PR 的 How this was verified（过去时，仅写实际运行过的内容，说明未验证项及原因）；PR 的 Risk and rollback（何时会坏、影响范围、回滚方式、不可逆项，无运行时影响可跳过）；Out of scope（明确边界，PR 中可放有意推迟的后续项）。
图表用 mermaid 必填：变更替换或改变现有行为时须同时画 Before 和 After 两张图，全新能力只需 After。约定：图中不得出现分号；数据流默认用带 autonumber 的 sequenceDiagram，展示每步发送/返回的载荷形状；参与者用真实实体名；用 Note over 分隔阶段或标注非显然步骤；拓扑需要时另加 graph TB 组件图。
方法：先收集真实机制（工单读代码/设计，未知则做 spike 或询问，不得编造流程；PR 用 git diff <base>... 通读自己的 diff）；自上而下起草并逐节检查；剥离所有外部引用；按真实调用图构建图表并逐箭头核对代码；验收章节写成可观察的终端副作用；发布前检查时态。
发布：Linear 工单用 Linear MCP 的 save_issue，描述以 Markdown 字面换行传入，更新已有工单传其 id。PR 将正文写入文件后按路径传入：gh pr create --base <base> --title "<title>" --body-file <path>；gh pr edit <number> --body-file <path>。不得在 PR 描述、提交信息或工单中加入编码代理署名。分支交接、实现、落地等操作尾部不属于本技能，由用户按需指定。