Use before proposing any architectural, modelling, or dependency decision; after making one; or when tempted to restructure existing code whose shape seems wrong. ADRs are the memory that stops agents from relitigating settled decisions across sessions.
78%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.claude/skills/adr-discipline/SKILL.mdADRs exist because agents have no memory between sessions. Without them, every session re-argues f64-vs-newtype for money, re-proposes the framework that was already rejected, and "improves" structure that is load-bearing for reasons not visible in the code.
rg -il '<topic keywords>' docs/adr/Yes: port/adapter boundaries, persistence and serialization choices, domain model shape (the money/percent newtype decision), dependency adoption or rejection, error-handling strategy, anything a future session might plausibly "helpfully" undo.
The sharpest case of "would be helpfully undone" is the core-innovation decision — the one choice that is the project's reason for existing. That gets an ADR and a mechanical tripwire gate that fails the build if the value flips (quality-gates): the ADR records why, the gate stops the silent revert an amnesiac would otherwise ship. ADR and tripwire are two halves of the same protection — argument and enforcement.
No: naming of one function, formatting, anything cargo fmt/clippy already
enforces, decisions fully expressed by a requirement in specs/ (link the
spec instead).
Use templates/adr.md. File: docs/adr/NNNN-short-title.md, NNNN sequential.
Keep it under a page. The two sections that matter most:
Statuses: proposed → accepted → (superseded by NNNN). Never edit an
accepted ADR's decision; supersede it with a new one.
Field-validated alternative for decisions scoped to one work item: the decision lives in the body of a dedicated commit — often a one-line tracker-state diff whose entire value IS the body ("Owner confirmed byte-exact parity is the bar; the shortcut is rejected, so X stays a hard prerequisite of Y"). Corrections of earlier decisions get the same treatment, naming what was wrong and filing the follow-ups. Written to the next agent, not to a changelog.
The rule that keeps this honest: a commit-body decision must be reachable
without archaeology — linked from the bead that carries the work. The
moment a decision constrains future structure (a boundary, a dependency,
a model shape — anything a later session might "helpfully" undo), it
graduates to a real ADR file; git log is not where anyone checks before
restructuring. Scoped-to-one-bead → commit body + bead link. Load-bearing
beyond the bead → ADR.
When a bead deliberately delegates a choice to the implementer ("engine choice is yours"), the implementer records the decision with its why and its application rule — that's an ADR (or a commit-body record + memory if narrowly scoped), not a silent pick.
ADRs may cite REQ IDs (a decision made to satisfy a requirement). Specs may
cite ADRs under ## Related ADRs. Code cites neither — structure and types
should make the decision legible; the ADR explains why.
igouss/gitweb-rs
9ef2429
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.