decision-log v1.0.7A

Immutable. This exact content never changes and is served at /api/v1/blob/1b8590353142fbff.

---
name: decision-log
description: >-
  Record or query architecture decision records (ADR) — Nygard template
  (context/decision/consequences) with a proposed/accepted/superseded/rejected status
  state machine, written to docs/decisions/NNN-slug.md plus the index table update —
  and, where the project keeps a handoff store, a reference line in it. Use when a semantic ruling or adjudication happens in
  a stage, or on "记录裁定" / "写进决策日志" / "ADR" / querying "决策 X 的现状". NOT for:
  writing the session handoff itself — the store references ADR numbers, never copies them.
slug: decision-log
version: 1.0.7
displayName: decision-log
---

# Decision Log（ADR 记录/查询）

## 定位

阶段内任何**语义裁定/拍板/设计裁决** → 当阶段写成 ADR（Nygard 模板），集中进
`docs/decisions/`，让「决策 X 的现状」可查询：status + 历史链（superseded 不删除）。

## 何时使用

- 用户说「记录裁定」「这个决策写进决策日志」「ADR」
- 阶段内发生语义裁定（审计裁定、拍板项、设计裁决）——**当阶段记，不攒批**
- 查询：「决策 X 的现状」「这个决定后来改了吗」

## 触发纪律

每次语义裁定后 3 分钟内完成记录。拿不准是否够格 → 记（轻量；比漏记好——历史链靠它）。

## 流程（记录）

```
- [ ] 1. 编号：docs/decisions/000-decision-log.md 索引最大号 + 1 → NNN
- [ ] 2. 文件名：NNN-slug.md（slug = 决策主题 kebab-case，如 001-rejectstreak-semantics.md）
- [ ] 3. 写 ADR（Nygard 模板 + 状态机，见下）
- [ ] 4. 更新 000-decision-log.md 索引表（# | 标题 | 状态 | 日期）
- [ ] 5. 交接存储同步（**条件步**）：项目**已有** `.handoff/` 存储时，为这条 ADR 登记**一条编号引用**（不复制内容）——
      条目标题镜像 ADR 序号（`NNN — {标题}`）便于两侧对照，正文写 ADR 位置 `docs/decisions/NNN-slug.md`；
      决策条目**不收独立引用字段**（把路径写进标题/正文即可），改判**另开一条**、取代关系由存储侧承载。
      写入口与命令形见 [`project-handoff`](../project-handoff/SKILL.md) 的写槽表（唯一权威面，本件不复制其参数面）。
      **无该存储 → 跳过本步**（只留 ADR 与索引），**不自主建存储**：建/迁由该件定义、须用户显式调用
```

## ADR 模板（Nygard）

```markdown
# NNN — {决策标题（含来源节，如 §4.1 C8）}

- Status: proposed | accepted | superseded | rejected
- Date: YYYY-MM-DD（{触发语境，如 S1.1 审计裁定}）
- 相关：{设计节/审计报告引用——路径，不复制}

## Context

问题/冲突背景：字面冲突、可选方案、触发证据（测试失败、审计发现）。

## Decision

- 决定内容（分条）
- 边界（什么不在本决策内）
- 落实方（哪个阶段/技能接线）

## Consequences

- 正面/负面后果
- 后续需要做的（如 S3 接线实现 X）
```

## 状态机

```
proposed ──→ accepted ──→ superseded
    └──────→ rejected
```

- **superseded**：被新决策取代——新 ADR 的「相关」注明「supersedes NNN」；旧 ADR 状态改 superseded，**不删除**（历史链保留）。
- **rejected**：评估后不采纳（proposed 阶段否决）。
- 查询时返回：当前 status + 完整链（NNN → superseded by NNN+1 → …）。

## 防双源

- `.handoff/`（项目工作存储）与设计文档只引用 ADR 编号（如「001 已定」），不复制 ADR 内容。
- spec（stage-spec）引用 ADR 编号记录 DoD 变更来源。

## 边界（分工）

| 相邻技能 | 分工 |
|---------|------|
| [`project-handoff`](../project-handoff/SKILL.md) | **交接存储的工具方**：本件只定「引一条编号引用、不复制内容」这条契约，`.handoff/` 结构与写命令参数面归它定义；阶段裁定 → 本技能写 ADR |
| `stage-spec` | DoD 变更需当阶段 ADR 记录——spec 引用编号 |
| `stage-gate` | 门禁检查「决策日志同步」断言 = 索引最新 |

## 完成标准（记录）

- [ ] `docs/decisions/NNN-slug.md` 存在（Nygard 三节 + status/date/相关）
- [ ] `000-decision-log.md` 索引已加行（#/标题/状态/日期）
- [ ] 3 分钟内完成（轻量流程，不追求篇幅）
- [ ] 无敏感信息（凭据不写值）

## 完成标准（查询）

- [ ] 返回决策 status + 历史链（含 superseded 链）
- [ ] 引用来源（设计节/审计/相关 ADR），不搬运全文

## 反模式

- 裁定发生但不记录（等「有空」——历史链断）
- 记录超过 3 分钟（过度润色；ADR 不是论文）
- superseded 后删除旧 ADR（链断）
- 往 `.handoff/` 复制 ADR 内容（双源）
- 项目无 `.handoff/` 就为登记引用而自建存储（建/迁须用户显式调用；本件**不建存储**——有存储时它照常经该件写入条目）
- 编号跳号/覆盖旧文件