Positioning
Any within a stageSemantic ruling/decision-making/design ruling → when the stage writes it as an ADR (Nygard template), consolidate into
docs/decisions/, making "the current state of decision X" queryable: status + history chain (superseded entries are not deleted).
When to use
- The user says "record the ruling", "write this decision into the decision log", "ADR"
- A semantic ruling occurs within a stage (audit ruling, decision-making item, design ruling) —record it in the current stage; do not batch it up
- Query: "the current state of decision X", "was this decision changed later"
Trigger discipline
Complete the record within 3 minutes after each semantic ruling. If unsure whether it qualifies → record it (lightweight; better than missing it — the history chain depends on it).
Process (recording)
- [ ] 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 template (Nygard)
# NNN — {决策标题(含来源节,如 §4.1 C8)}
- Status: proposed | accepted | superseded | rejected
- Date: YYYY-MM-DD({触发语境,如 S1.1 审计裁定})
- 相关:{设计节/审计报告引用——路径,不复制}
## Context
问题/冲突背景:字面冲突、可选方案、触发证据(测试失败、审计发现)。
## Decision
- 决定内容(分条)
- 边界(什么不在本决策内)
- 落实方(哪个阶段/技能接线)
## Consequences
- 正面/负面后果
- 后续需要做的(如 S3 接线实现 X)
State machine
proposed ──→ accepted ──→ superseded
└──────→ rejected
- superseded: superseded by a new decision — the new ADR's "Related" notes "supersedes NNN"; the old ADR's status is changed to superseded,not deleted(the history chain is retained).
- rejected: evaluated and not adopted (rejected at the proposed stage).
- On query, return: the current status + the full chain (NNN → superseded by NNN+1 → …).
Prevent dual sources
.handoff/(project work storage) and design documents only reference the ADR number (e.g., "001 decided"), without copying the ADR content.- The spec (stage-spec) references the ADR number to record the source of the DoD change.
Boundaries (division of labor)
| Adjacent skills | Division of labor |
|---|---|
project-handoff |
The tool-side party that hands off storage: this item only defines the contract of "reference a number, do not copy the content";.handoff/ its structure and write-command parameter surface are defined by it; stage ruling → this skill writes the ADR |
stage-spec |
A DoD change requires a current-stage ADR record — the spec references the number |
stage-gate |
The gate check "decision log sync" asserts = index up to date |
Completion criteria (recording)
-
docs/decisions/NNN-slug.mdexists (Nygard three sections + status/date/related) -
000-decision-log.mdThe index has the row added (#/title/status/date) - Completed within 3 minutes (lightweight process; length is not the goal)
- No sensitive information (credentials are not written as values)
Completion criteria (query)
- Returns the decision status + history chain (including the superseded chain)
- Cites the source (design section/audit/related ADR) without copying the full text
Anti-patterns
- A ruling occurs but is not recorded (waiting for "free time" — the history chain breaks)
- Recording takes more than 3 minutes (over-polishing; an ADR is not a thesis)
- Deleting an old ADR after it is superseded (the chain breaks)
- To
.handoff/copying the ADR content (dual sources) - If the project has no
.handoff/, creating storage on its own just to register references (creation/migration must be explicitly invoked by the user; this itemdoes not create storage— when storage exists, it still writes entries through that item as usual) - Skipping numbers/overwriting old files