record-decision

To write an ADR, you generate a markdown file formatted as docs/adrs/adr-<ID>-<slug>.md using a standardized adr-template. This file captures the context, alternatives, decision, consequences, and rollback plan, while automatically updating the workflow state.

An architecture decision record template should include sections for context, alternatives considered, the final decision, consequences, and rollback plans. It also helps to include links to related PRDs or specs for comprehensive traceability.

You can validate your ADR files by running the validate_adr.py script. This script checks your generated markdown files to ensure they follow the required sections, file paths, and formatting rules defined by the standardized template.

You use ADRs to capture non-trivial architectural choices specifically at Stage D of the VibeFlow workflow. This ensures critical context, alternatives, and rollback plans are consistently documented rather than overlooked.

The best way to track architecture decisions is using ADRs that centralize documentation and explicitly link to related PRDs or specs. This approach maintains consistent documentation across projects and updates the workflow state automatically.