用途
ux-writing 是一个关于「用户可见文本」的质量准则集合，所属仓库为 scarletkc/hatoba。其定位是：用户可见文本属于产品行为，应与代码保持相同的质量线。每条规则都提炼自评审中真实发现的缺陷，并保留反例以体现推理过程。遇到疑问时，以「刚遇到问题的用户」视角重读输出。
主要能力（按主题分节）
状态输出与诊断
- 报告生效值，而非存储值：状态展示应回答「运行时会怎样」，需按运行时方式解析，包含环境变量与分层配置。反例：配置查看器显示「API key set: no」，而环境变量中实际存有下次运行会使用的 key。
- 诊断在失败时保持真实：某层配置加载失败时，回退到仍能加载的最完整状态，而非空白默认值；误报的诊断比中止更糟。
- 展示差异，而非全量转储：健康/诊断命令只列偏差及来源，详尽清单属于专门的 inspect 命令。
- 按声明粒度标注：复合值中某个子部分来源不同，只在子部分上标注，不重标整个块。
- 新增元数据后重读相邻标签，避免后缀与既有值标签冲突。
- 机器可读输出是契约：TSV/JSON 等格式不得添加装饰、提示或注释，信息性文本走 stderr 或人类格式路径；缺失也属于契约，需写负向测试。
- 永不截断载荷：诊断中的路径、ID、URL 在窄终端下也不得省略。
错误消息
每个错误回答三个问题：发生了什么、在哪里、现在该做什么。最强模式是：指出出错的文件或输入，列出被拒字段与允许字段，并说明被拒设置应放在哪里。宁可显式失败，也不要静默降级。
文档
- 每份文档只有一种职责（持久契约、提案、调查、TODO、带日期的工单或运行手册，居其一）。
- 每个事实只有一个权威归属；其他地方通过单条具体链接指向它。
- 改述加链接是缺陷而非周全：若某节重复权威内容再写「详见 X」，那它本身就成了完整契约，应删除重复。
- 优先最小充分修改，保留未受影响的措辞、结构与理由。
- 插入内容时尊重相邻关系，避免把脚注与其表格割裂。
- 形容词需要证据；README 每个部分只做一件事；页面按读者最先需要的顺序排布，当一个任务变成多个时拆分。
会过时的信息
- 不要快照比文档变化更快的值：版本号、镜像标签、构建 ID、部署提交哈希、对象计数、过期日期、「当前在线/尚未发布」等属于变更日志、git 历史或发布工单。若页面确需展示当前值，应在构建时从权威来源生成。
- 指针指向符号而非仓库：给出具体文件加可搜索的符号、函数、数据键或标题；仅当事实来自无单一文件真相的有序集合，或目录本身是目录清单时才指向目录。
- 文档无法观测运行时：仓库说明提交应如何表现，只有运行中的系统知道哪个提交在线、是否健康；文档记录回答问题的命令或控制台，绝不把已合并代码升格为「已部署」。
最终状态，而非到达它的路径
- 陈述代码做什么，而非差点做什么：标题、摘要、注释描述已交付行为；中间尝试与被放弃的选项属于产生它们的讨论。
- 注释只承载非显然原因：排序要求、上游缺陷、平台怪癖等下一读者无法从代码恢复的约束。
- 证据服务于读者决策而非作者疑虑：读者需要据此行动的断言（更快、更安全、优先用它）要给出依据；单纯陈述代码做什么则不需要。
- 交付物不自述生产过程：生成的报告、演示、导出与截图承载发现、数值与指令，而非实现说明、方法理由或作者后续步骤。
行为变更的同步清扫
行为变更在文案站点达成一致前不算完成。按遗忘概率从高到低检索旧措辞：--help 选项字符串（最常漏）、集中消息/字符串模块与命令 docstring、README 与文档页、随附技能文件、插件元数据、MCP 工具描述（这是给智能体的 UX，同样适用）、描述旧行为的路线图或状态说明。随后重新解析涉及的链接，处理重命名标题导致的锚点断裂与移动文件导致的相对路径失效。
文案测试
- 断言扁平化文本或行为，而非控制台格式：用
" ".join(output.split())扁平化后再做子串断言。 - 清除颜色环境变量泄漏：测试运行前清除 FORCE_COLOR / COLORTERM，避免 ANSI 混入捕获输出。
- 机器格式除断言必须存在的内容，还要断言必须缺失的内容。
使用方式
资料仅提供该技能在外部分发站点的页面地址（https://www.skills.sh/scarletkc/hatoba/ux-writing），未提供安装命令、调用方式、运行平台或依赖说明，这些暂未提供。
适用场景
适用于编写或评审用户可见输出、错误与帮助文本、文档、代码注释以及生成的交付物（报告、演示、导出等），也适用于触发行为变更后的文案同步排查与文案测试编写。
限制
资料未说明作者、许可、版本、收费、维护状态与平台支持，这些暂未提供。所列规则是判断准则，不含可直接执行的工具代码或自动化检查脚本（资料中仅出现测试建议与示例片段）。