adr-assistant_skill

Overview

This skill helps create, analyze, and maintain Architecture Decision Records (ADRs) to support clear, traceable architectural choices. It automates ADR numbering, enforces a consistent template, and surfaces conflicts, dependencies, and improvements across existing records. The assistant also researches alternatives and produces implementation plans with measurable success metrics.

How this skill works

The assistant scans the project's ADR index and adr/ directory to identify existing decisions and relationships. It generates new ADRs using a standard template, researches alternatives via knowledge sources, and outputs pros/cons, consequences, and an implementation timeline. It can also review and suggest edits for current ADRs, flag conflicts, and update the ADR index.

When to use it

• When choosing between major technology options (e.g., GraphQL vs REST).
• When documenting a finalized architectural decision for traceability.
• When updating or reviewing existing ADRs for conflicts or gaps.
• When preparing an implementation plan with timelines and metrics.
• When researching and comparing 3–5 viable alternatives for a decision.

Best practices

• Consider at least three alternatives and document clear reasons for rejection.
• Include measurable success metrics and a realistic timeline in the Implementation section.
• Link related ADRs and surface dependencies or conflicts explicitly.
• Document concrete consequences (positive, negative, neutral) and risk mitigations.
• Keep each ADR focused on one decision and update the ADR index after changes.

Example use cases

• Generate ADR-0012 to compare GraphQL and REST including tradeoffs and implementation steps.
• Review existing ADRs to detect contradictory choices or untracked dependencies.
• Create an ADR that records adoption of a new package manager or build tool.
• Draft an ADR for database selection with performance and operational consequences.
• Update an ADR to mark a decision as Superseded and link to the replacement.