documentation-and-adrs

Architecture decision records document context, chosen options, rejected alternatives, and consequences to explain why a change exists. This prevents future maintainers from rediscovering the reasoning behind architecture, API, workflow, and migration decisions.

Preventing documentation drift requires verifying commands, paths, versions, and counts against source code and tests before authoring. Evidence-first documentation reads source-of-truth artifacts and runs validators to keep READMEs, runbooks, and migration guides accurate.

The best way to document migration guides is producing documentation only after reading source-of-truth artifacts and running relevant grep, tests, or link validators. This evidence-first approach verifies proposed changes against existing behavior and records verification commands for reliable discovery.

Decision records are needed when changes to architecture, APIs, workflows, migrations, or operational behaviors create future constraints or operational requirements. They capture the why-so decisions and review triggers required for reliable future maintenance and discovery.

Yes, you can verify a proposed change against existing docs and then produce a decision record or updated user-facing documentation with evidence and alternatives. This ensures durable, evidence-backed documentation stays aligned with real source behavior.

Manual documentation without verification commands risks doc drift, where READMEs, setup guides, and runbooks become inaccurate. Without evidence-first authoring and source-of-truth validation, future agents and maintainers lose reliable discovery of why changes exist.