develop-adr

Assign a sequential number and short noun-phrase title, set the status to Proposed, describe the context and forces behind the decision, state the decision in active voice, and document positive and negative consequences. This Skill follows Michael Nygard's lightweight ADR format.

The Nygard format is a lightweight ADR structure with five sections: title, status, context, decision, and consequences. It was introduced by Michael Nygard to capture architectural decisions as short, standalone documents that evolve through statuses like Accepted or Superseded.

Create an ADR when making significant technical decisions that affect system architecture, choosing between technology options, or establishing patterns future development must follow. ADRs capture the why behind decisions, which general documentation typically omits.

New ADRs start as Proposed, then move to Accepted after team review. They can later become Deprecated or Superseded by a newer ADR, with the superseding ADR number referenced. Status changes are tracked rather than rewriting the original record.

Lightweight ADRs intentionally omit deep analysis sections found in heavier architecture documentation, so they may not suit decisions requiring formal risk assessment or compliance sign-off. They work best as concise decision logs, not full design specifications.