create-architectural-decision-record

The `create-architectural-decision-record` skill is designed to streamline the creation of Architectural Decision Records (ADRs), providing a structured approach to documenting significant architectural decisions in software projects. It addresses the common challenge of inconsistent or incomplete decision documentation by generating ADRs that are both human-readable and optimized for AI parsing. By standardizing the format and ensuring all critical elements are captured, this skill helps teams maintain clarity and traceability in architectural choices, reducing the risk of miscommunication and future rework.

This skill offers several key capabilities, including structured input handling for context, decision rationale, alternatives, and stakeholders. It enforces input validation to ensure completeness before generating the ADR, supports detailed documentation of positive and negative consequences, and uses coded bullet points for clarity in multi-item sections. ADRs produced by this skill follow a standardized front matter format and are saved with sequential naming conventions in a dedicated documentation directory, enabling easy version tracking and systematic organization of architectural records.

Use cases for this skill include software engineering teams, solution architects, and technical leads who need to formalize decisions for complex projects. It is particularly valuable in environments where architectural consistency, regulatory compliance, or knowledge sharing is important. By generating clear and structured ADRs, this skill supports decision transparency, facilitates onboarding of new team members, and enhances long-term maintainability of software architecture.