decision-records

decision-records is a skill for managing ADR-style architecture (and product, security, policy, legal, and other open-typed) decision records via a bundled Python tool, `scripts/decisions.py`. It solves the recurring problem of keeping a repository's decision log consistent: minting stable IDs, generating a central INDEX.md, self-healing cross-links across all docs, and enforcing the lifecycle that separates draft candidates from finalized, held-firm decisions.

The tool exposes commands to build/regenerate the index (with `--relink`), check the tree in CI (exiting non-zero when stale), promote drafts into accepted records, rename draft IDs, and install itself into a repo via a symlink plus a pre-commit check. Records live under `docs/decisions/` in three stages — drafts (four-uppercase-letter mnemonic IDs), accepted (`accepted/<type>/` with a global zero-padded counter), and archived (retired, superseded or deprecated). Types are open lowercase slugs whose directories define the set. The convention treats accepted decisions as immutable except by supersession; on a superseding promotion the tool automatically retires the old record, flips its status, and records the forward/backward links. A key safety rule is enforced in software: an accepted decision may never reference a draft, and the tool refuses breaching promotions with a copy-paste fix.

It targets engineering and governance teams that want their decision history to stay authoritative and machine-validated rather than drifting. The skill is explicit that promotion and supersession are finalizing, semi-irreversible acts requiring the user's explicit human sign-off in the current turn — an unusually strong, safety-conscious guardrail against an agent finalizing decisions on its own.