decision-record-writer

To write an Architecture Decision Record with immutable history, use an append-only supersession model that creates new ADRs linked to prior decisions instead of overwriting them, preserving the full decision rationale trail over time.

Documenting a technical decision log requires a real architectural choice with at least two plausible alternatives, explicit tradeoffs, and mandatory negative consequences to pass rigor checks and produce a governance-ready Markdown file.

Supersede prior architecture decisions by creating a new ADR for the same topic key using an append-only model, ensuring the supersession link connects the new record to the original while keeping the previous decision rationale immutable.

You need to create an ADR when there is a genuine architectural choice to document. The process rejects vague feature requests masquerading as decisions by requiring at least two plausible alternatives with explicit tradeoffs and negative consequences.

A structured Architecture Decision Record should include context, decision, alternatives, tradeoffs, consequences with mandatory negatives, risks, scope, and review trigger sections to ensure comprehensive technical decision traceability.

Yes, the approach enforces one-decision-per-ADR validation for technical documentation, ensuring each Markdown file captures a single architectural choice to maintain strict governance and decision traceability across your repository.