review-adr

Review Architecture Decision Records for completeness, accuracy, and reasoning.

Updated Feb 20, 2026

Search Tags:#architecture #code review #documentation #technical writing #decision record #adr

Ready to run

npx skills add https://github.com/jamesc/skills --skill review-adr

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: review-adr
Source: https://github.com/jamesc/skills/tree/main/skills/review-adr
Command: npx skills add https://github.com/jamesc/skills --skill review-adr

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill ensures Architecture Decision Records (ADRs) are comprehensive, technically sound, and clearly reasoned, preventing the adoption of weak or harmful design choices.

Core Features & Use Cases

Multi-pass review: Applies distinct analytical lenses (structural, reasoning, adversarial) to uncover a wide range of issues.
Code verification: Validates code examples against the actual codebase for accuracy.
Use Case: Before merging a critical ADR for a new language feature, use this Skill to perform a deep review, catching potential flaws in the design, implementation plan, and reasoning that might otherwise lead to costly mistakes.

Quick Start

Use the review-adr skill to perform a full three-pass review on the ADR file docs/ADR/0015-new-feature.md.

Frequently Asked Questions about review-adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I review an Architecture Decision Record to ensure it is comprehensive?▼

To review an Architecture Decision Record comprehensively, apply a multi-pass analysis covering structural template adherence, factual accuracy, and adversarial testing of assumptions. This process validates code examples against the codebase and challenges reasoning to ensure technical soundness.

What is adversarial testing in the context of architecture documentation?▼

Adversarial testing in architecture documentation is an analytical lens that challenges the assumptions and reasoning within an Architecture Decision Record. It actively uncovers potential flaws in design choices to prevent the adoption of harmful technical decisions.

How do I validate code examples in a technical decision record against my codebase?▼

You validate code examples in a technical decision record by running a dedicated verification pass against the actual codebase. This checks factual accuracy, ensures the proposed implementation plan is viable, and prevents costly mistakes before merging.

When do I need to use a formal review process for ADRs?▼

You need a formal review process for ADRs before merging critical architectural choices, such as introducing a new language feature. It ensures institutional knowledge is maintained, reasoning is sound, and flawed design choices are caught early.

Does this ADR review approach work without external dependencies?▼

Yes, this ADR review approach works without external dependencies. It operates as a standalone skill using internal scripts and references to perform structural validation, reasoning checks, and codebase verification directly on your documentation.