ccdawn/briefbound-skills/briefbound-adr

Briefbound ADR 决策记录

目标

把已拍板的架构/技术决策落成可追溯的 ADR：为什么这么定、放弃过哪些选项、带来什么后果。MADR 风格（背景、决策、备选方案、后果）＋状态流转与决策债务提示，让未来维护者读到"当时为什么"，而不是只有"现在是什么"。

Briefbound task contract

• Context Boundary: 定案决策及其动机、被否选项、相关会话结论与 git diff、项目 ADR 目录约定（默认 docs/adr/）；不重做方案设计。
• Output Contract: 单条 ADR（编号、状态、日期、背景、决策、备选方案、后果）+ 索引更新 + 状态流转记录 + Route Out。
• Allowed Action: 直接写 docs/adr/（或项目约定目录）下的 markdown；读 git diff、会话与既有文档取证；不改业务代码。
• Success Evidence: 决策、背景、备选、后果四要素齐备且可溯源；索引计数与条目一致；superseded 条目互链新旧。
• Stop Condition: 方案未拍板、事实源不足无法还原动机、或用户要的是状态盘点而非决策留痕。
• Route Out: 未拍板讨论回 briefbound-planning；状态快照归 briefbound-project-memory；验证后残留 briefbound-development-cleanup；briefbound-router 或 BLOCKED。

统一调用契约

• 只处理 Briefbound task contract 范围；不匹配回 briefbound-router 或更具体 owner，复合任务不吞其他 owner。
• 用户可见内容默认中文、保留技术字面量；Route Out 仅以 Briefbound task contract 为准；有自然闸门（需用户裁决、批准或被阻塞）时末行 下一步建议: <一个具体动作>，否则声明继续已授权工作。

激活闸门

任一：用户要求记录决策或写 ADR；技术选型刚定案要存档；"为什么这么设计"需要留痕；要 supersede 旧决策；新工作与已接受决策冲突需梳理。排除：仍在讨论未拍板（回 briefbound-planning 或 briefbound-router）、项目状态盘点（briefbound-project-memory）、契约设计本身（briefbound-api-contract）。

记录方法

• 一条决策一个文件：NNNN-<标题>.md，序号递增不复用；状态 proposed → accepted → superseded，上下文变化只改状态，不改历史结论。
• 四要素：背景（约束与动机）、决策（定案与理由）、备选方案（被否选项及否决理由）、后果（收益、代价、风险）。
• 取证：从会话结论提炼理由，从 git diff 还原实施范围；无证据的推断标 TODO(待核实)，不编造动机。
• supersede：新条目链接旧条目，旧条目只改状态并指回新条目；不删除、不改写已接受内容。
• 决策债务：后续工作与 accepted 决策冲突时，先提示债务（哪条决策、冲突点、建议路径），由用户裁决后走 supersede，不静默绕开。

与相邻 owner 的边界

• briefbound-project-memory 记现在是什么样（状态快照）；本技能记当时为什么这么定（决策时间线）。同一事件两边可各记一笔，互不替代。
• briefbound-planning 做方案讨论与任务拆解；方案拍板后的留痕动作归本技能。
• briefbound-api-contract 产出契约设计；设计构成重大决策时本技能为其落 ADR，不重复设计。
• briefbound-readme-optimization 面向新读者讲怎么用；ADR 面向未来维护者讲为什么。

致谢

记录结构参考 MADR 模板（github.com/adr/madr，MIT OR CC0-1.0），表述全部重写；取证与留痕工作流借鉴 anthropics/skills 的 doc-coauthoring（Apache-2.0）。

输出

结论: <新落 ADR 或状态流转的条目与编号>
验证: <索引一致性、链接与四要素核对结果>
下一步建议: <一个具体动作；否则声明继续已授权工作>