Dsh Prose Standard

---
name: dsh-prose-standard
description: "撰写、审查、恢复、精简或审计 Markdown、API 文档、代码/测试注释、提示、诊断及 UI/CLI 文案，判断哪些合同必须写明。"
---

# dsh-prose-standard

本 Skill 仅用于当前项目。用户授权、项目 AGENTS.md 和实际宿主能力优先。

## 范围和模式

这是写作判断指导，不是机械清单。使用用户指定的文件/目录/diff；没有可确定范围时只问范围，不扫描全仓。review/audit 只报告，write/fix/trim 才修改。默认自主处理明确项；只有用户要求讨论/校准才给交互备选，不让“交互模式”代替写入授权。

排除 vendor/第三方源、冻结档案，不沿 symlink 越界。生成目录、快照与 fixture 是派生物，先追生成/场景 owner，再按获授权的行为变化重生成。维护双语时可从任一语言发起，另一侧做最小相应更新。

## 完整命题优先

逐项识别并保留：主体与动作、条件、时间/顺序、must/may/never 等强度、负面保证与例外、所有权、副作用、失败和后果。词少不是质量依据；不通过删除安全、兼容或恢复条件达成精简。

调用点保留本地必需的行为/失败/归属/时机，长篇算法、架构理由、历史和例子链接唯一 owner。一个链接不能替代调用者必须当场知道的合同。理由若能防止合理误用就保留，代码已说明的控制流叙述删除。

## 不同位置必须表达的内容

- 公开 API：返回区别、throws/reject、副作用、所有权、取消、时机与持久保证。
- 内部/模块注释：非显然不变量、跨处结构、依赖与责任、竞争顺序和安全边界；不逐行讲实现。
- 测试注释：非显然 fixture、平台照顾、真实入口或间接观测为何必要；不做测试流程解说。
- 指南：前提、必要操作、真实入口、成功观测与简短风险/恢复。README：消费者配置、语义、失败、限制、扩展点与模型可见影响。
- 决定记录：独有机制、理由、替代、后果、已验证证据和缺口；已实现部分用当前事实。复盘保留事件、证据、因果、影响与预防，不当作普通现状文档删历史。
- Skill/代理规则：范围、行为约束与适用限制；不能压成没有动作依据的口号。
- 示例/配置：不显然的访问限度、加载顺序、安全立场、重放例外和误用后果；不复述配置清单。
- 诊断：失败主体/路径、违反条件与可行纠正，删除内部执行独白。

prompt、description、UI/CLI 与可访问文案属于行为。检查实际消费方、locale、tooltip/placeholder 和快照；只做 prose audit 时，没有所属可运行证据就保留原文并说明延后，不能偷偷改行为。生成器只抽取一句时，该句须独立完整。保留机制名和有意义的语气/时序强调，不把 contract、boundary 等精确技术词一律禁用。

## 执行与校准

阅读 owner 后逐段分类 keep/add/trim/restore/restructure/defer；必要合同缺失时补回，不是单向删字。明确项直接执行，真正边界项需有两种都完整保留命题的可行版本才值得讨论。只在授权范围内应用决定，不自行修改全局偏好/记忆。

检查当前事实、相关导出片段、双语含义及项目规定验证，报告检查范围、改动、刻意保留和待定项。

例如：“协调器按会话串行写入，在 dispose 完成前刷出事件，并把后端失败返回调用者。”不能缩成“协调器管理持久化”；会话隔离、结束时序和错误可见性是三项独立保证。

来源、适配边界和许可证见 [provenance.md](provenance.md)。