adr-methodology_skill

Overview

This skill helps teams create, analyze, and generate Architecture Decision Records (ADRs) using a structured, human-in-the-loop methodology. It standardizes criteria generation, option comparison, and final ADR drafting using MADR templates while preserving human accountability. The workflow supports reusable state across sessions to iterate on criteria, matrices, and the final decision document.

How this skill works

Start by collecting problem context, constraints, stakeholders, and candidate options. The skill selects an assessment framework (Salesforce Well-Architected, Technical Trade-off, or a custom set), generates evaluable criteria, and persists them to a session file. It then rates options against those criteria with risk levels and rationales, produces a comparison matrix, and finally generates a MADR-formatted ADR including an AI disclosure section. Humans are prompted to refine criteria, ratings, and the final choice at each stage.

When to use it

• When asked to create an ADR or document an architectural decision
• When comparing multiple architectural options or technologies
• When you need structured assessment criteria or a decision matrix
• When you want a MADR-compliant ADR draft with AI-assisted content
• When you need to analyze trade-offs and assign risk ratings

Best practices

• Provide clear project context, constraints, and stakeholder lists before analysis
• Choose the framework that matches the decision scope (enterprise vs tooling)
• Keep criteria specific and evaluable; include a reversibility criterion
• Iterate: refine criteria first, then ratings, then finalize the ADR
• Record rationale for every rating so decisions remain auditable

Example use cases

• Selecting a primary database for a user service with ACID requirements
• Evaluating managed cloud services vs self-hosted alternatives
• Choosing a front-end framework balancing UX, developer velocity, and vendor lock-in
• Creating organizational ADRs for security and compliance patterns
• Generating assessment criteria for a migration or vendor selection project