用途
write-go-docs 是一个针对 Go 源码文档的技能，用于对包和声明注释、示例以及废弃通知进行撰写、修订、精简或审计。其核心原则是把“信息增益”作为文档的准入测试：当一段源码文档能减少超出名称、签名、类型和直接上下文之外的不确定性时，它才有存在价值。该技能要求把改动限制在 Go 源码与 Go 示例测试内，将 README 和架构类工作交由各自的文档流程处理。
主要能力
- 撰写、修订 Go 的包注释与声明注释。
- 精简或删除无信息增益的注释（对每条现有或拟新增注释应用“删除测试”）。
- 编写或审计 Go 示例（Example、ExampleFoo、ExampleFoo_Bar）。
- 撰写废弃说明，以 Deprecated: 开头的独立段落呈现，并在仓库证据支持时指明受支持的替代方案或迁移约束。
- 支持仅审计或仅评审请求：保持源码不变，返回有证据支撑的决策。
- 识别带有 // Code generated ... DO NOT EDIT. 标记的文件为只读，并报告拥有其文档的生成器或源工件。
使用方式
该技能遵循用户指定的文件、包、声明或 diff，仅在需要确立公开行为或持久理由时扩展到调用方、测试、接口、实现与历史。它会检查 go.mod、邻近文档风格以及配置的校验规则（当语法或 lint 政策可能依赖它们时）。代码与测试被视为行为的证据，而非未声明意图的证明；当重要理由仍未解决时，会记录一个聚焦的维护者问题。
判断哪些内容值得文档化时，默认倾向是删除或跳过每个候选对象，只有当能指出声明本身未明显表达的具体信息时才提升它。每条事实只由一个注释拥有，而不是在构造函数或方法上重复类型的契约。导出状态被视为审计触发点，而非 prose 有用的证据；当配置的校验强制要求覆盖率时，会写出最短且符合约定的准确摘要，并报告因 lint 驱动的妥协。
适用场景
该技能用于记录阅读者相关但声明本身未揭示的知识，包括：语义保证、有效状态、不变量与边界条件；零值行为、所有权、生命周期、变更与资源释放；并发安全性、阻塞、取消、顺序与幂等性；错误、部分结果、panic、副作用与重试影响；包职责、跨包关系与持久权衡；以及需要示例说明的非显而易见组合或误用风险。
限制
文档仅应记录声明未明显表达的信息，默认应删除或跳过无信息增益的注释。常规构造函数、访问器、setter、包装器以及 (value, ok) 查找，只有在添加了所有权、同步、校验、缓存或特殊零值行为等语义时才应被文档化。README 与架构类工作不属于本技能范围。当可执行的验证不可用时，需直接检查注释位置与示例命名，并报告该限制。对于仅审计请求，使用只读检查并在不编辑的情况下报告发现；对于修订请求，完成所请求的编辑与相关验证，并报告实质性变更、有意省略、未解决的理由、lint 驱动的低信息注释以及存在的验证限制。
验证与完成
对改动的 Go 文件运行 gofmt；为文档示例运行最窄范围的相关 go test 命令以及仓库配置的文档或 lint 检查；使用 go doc 验证改动的关联、摘要或分组；当链接或标题需要渲染验证时，使用本地 pkgsite（若可用）。