architecture-decision-records

To document architecture decisions, the Skill detects decision signals during design discussions or pull request reviews, gathers context and alternatives, and drafts structured ADR files in a docs/adr directory after explicit user confirmation.

An Architecture Decision Record (ADR) is a structured document that captures the context, alternatives, and reasons behind a repository-level choice. You need one when selecting frameworks, databases, API designs, or deployment patterns so future contributors understand the rationale.

To create ADRs safely, the Skill scans existing files in the docs/adr directory to assign incremental ADR numbers and updates the README index. It prompts for user confirmation before writing any files to prevent overwriting prior decision records.

Yes, you can retrieve past design decision rationale by asking the Skill to locate and present the Context and Decision sections of existing ADRs. It also suggests creating a new ADR when architecture changes are proposed during reviews.

No specific developer tools or dependencies are required. The ADR workflow operates by scanning your repository files, assigning incremental numbering, and updating the docs/adr README index directly within your existing coding sessions.

The best way to record database or framework selection rationale is to draft a concise ADR that captures the alternatives considered and the consequences of the choice. The Skill initiates this during developer conversations or planning meetings for review.