agentic-ctx/skills/goal-first-tech-doc.md

Goal-First Tech Doc

用于新写或重构技术文档。目标是让读者最快知道：这份文档为谁解决什么问题，做到什么算完成，如何最小复现。

Use When

• 写 README、runbook、design note、tool usage、实验复现说明。
• 把抽象说明改成可执行文档。
• 压缩一份过长但重要的技术文档。

不要用于：

• 只修错别字。
• 论文/slide/marketing 文案。
• 技术正确性审查。

Required Inputs

• 文档目标或现有草稿。
• 目标读者。
• 相关命令、配置、代码、路径或接口。

Output

重写后的文档或提纲，必须包含：

• Goal。
• Prerequisites / Context。
• Steps or Design。
• 一个最小例子。
• Caveats / Failure Modes。

Rules

• 目标先于背景。
• 信息先于修辞。
• 删除不增加行动能力的句子。
• 保留前提、约束、错误处理和边界条件。
• 只要提到命令、接口、数据格式、目录结构，优先给最小例子。
• 如果信息缺失但不阻塞，明确写假设。
• 如果信息缺失会误导，先请求补充。

Preferred Shapes

短任务文档：

1. Goal
2. Steps
3. Example
4. Caveats

短设计文档：

1. Goal
2. Constraints
3. Design
4. Example
5. Tradeoffs