Forge-Architecture-Decision-Records

An ADR captures the decision title, status, context, problem, chosen decision, alternatives considered, consequences, and related requirements. This Skill provides a six-step procedure from identifying significant decisions through linking related knowledge.

Create an ADR when a decision affects system structure, data architecture, integration, security, scalability, or long-term technical direction. Skip ADRs for minor coding choices, temporary experiments, or routine implementation decisions without future impact.

ADRs should live in the project documentation structure, typically under docs/decisions/ with sequential naming like ADR-0001-workspace-model.md. Projects maintain their own decision records while the Skill provides the capability and template.

An ADR records a single decision with its reasoning, alternatives, and consequences at a point in time. Architecture documentation describes the current system design; ADRs preserve why it became that way and complement rather than replace design documents.

ADRs do not make architectural decisions, replace design activities, or define implementation standards. They only document decisions after they are made, so they depend on disciplined use whenever significant choices occur.