adr-writer

The adr-writer skill serves as a structured assistant for software engineers and architects to maintain high-quality technical documentation within a repository. By strictly adhering to the Design It! methodology, this tool facilitates the creation of Architecture Decision Records (ADRs) that explain the 'why' behind critical technical choices, ensuring that team knowledge is preserved over the long term and decisions are easily auditable during code reviews or system refactoring. It provides a standardized template including status tracking, context analysis, specific decision statements, and a thorough assessment of positive and negative consequences, helping teams avoid architectural drift and improve decision-making transparency.

• Provides a pre-configured markdown template for ADRs, ensuring all required sections (Status, Context, Decision, Consequences) are included.

• Guides users through the architectural decision lifecycle, from Draft and Proposed to Accepted, Superseded, or Deprecated statuses.

• Helps identify whether a specific technical change constitutes an architectural decision based on established criteria.

• Encourages best practices such as keeping ADRs focused, short (1-2 pages), and co-located with version-controlled source code.

• Facilitates the archival process by providing a clear protocol for marking decisions as Superseded rather than deleting them.

• Users should input the title and scope of their architectural change to receive a formatted ADR draft.

• Ideal for use during the design phase of new features, system migrations, or when responding to complex technical challenges requiring consensus.

• Best practices recommend storing these documents in a specific directory (e.g., docs/adr/) to ensure they remain discoverable alongside the relevant codebases.

• The output is intended to be treated like code, meaning it should be subject to peer reviews and PR processes before being marked as Accepted.

• Adheres to the principle of one decision per file to maintain clarity and ease of maintenance in evolving software architectures.