SuperAPI AI Directory

decision-log

General & other

View repository

Updated 10-16 02:31

About this skill

Decision Log (ADR recording/query)

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.md exists (Nygard three sections + status/date/related)
  • 000-decision-log.md The 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