skills.rest
real-case
real-caseCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr-review

Reviews a proposed Architecture Decision Record for structure, grounding, and readiness before acceptance.

Updated Apr 16, 2026
Search Tags:#documentation#validation#adr#mcp#review#architecture decision record#codebase grounding
One-click install
npx skills add https://github.com/real-case/marvin-toolkit --skill adr-review-real-case
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-review
Source: https://github.com/real-case/marvin-toolkit/tree/main/plugins/marvin/skills/adr-review
Command: npx skills add https://github.com/real-case/marvin-toolkit --skill adr-review-real-case

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Proposed Architecture Decision Records often contain placeholder residue, broken cross-references, or claims that do not match the actual codebase, and teams lack a consistent way to verify a record is ready before ratification. ## Core Features & Use Cases - Structural Validation: Checks required sections (Context, Decision, Consequences), placeholder residue, header sanity, and cross-reference integrity via the adr MCP audit action. - Codebase Grounding: Verifies that files, modules, versions, and configuration values cited in the record actually exist and match the repository. - Formal Auto-Fixes with Verdict: Mechanically fixes formatting, links, and fillable placeholders, then issues a READY_FOR_ACCEPTANCE verdict or a numbered defect list. - Use Case: After drafting ADR-0031 with /marvin:adr, run this review to confirm every claim is grounded in the repo and formal defects are fixed before a human ratifies it with /marvin:adr-accept. ## Quick Start Ask the assistant to review ADR 31 and tell you whether it is ready for acceptance.

Frequently Asked Questions about adr-review

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

FAQPage Schema
How do I review an Architecture Decision Record before accepting it?▼

Invoke the review with the record number or a title fragment, such as "review ADR 31". The skill validates structure, grounds every claim against the codebase, fixes formal defects, and returns a readiness verdict or defect list.

What does an ADR readiness check actually verify?▼

It verifies required sections exist with real content, no placeholder residue remains, cross-references resolve, and cited files, versions, and config values match the repository. It also checks consistency with existing accepted records.

Can the ADR review change the decision or mark it accepted?▼

No. The review never edits the substance of the decision and never sets the status to accepted. Ratification is a human action performed through the separate adr-accept command, which runs its own deterministic gate.

What kinds of defects does the ADR review fix automatically?▼

It only fixes formal defects: formatting issues, broken links, unambiguous ADR reference typos, and placeholders with a mechanical fill such as today's date or the record's own number. Substantive gaps are reported as defects, never written.

Can I review an already accepted or superseded ADR?▼

No. The review targets proposed records only. For accepted, superseded, deprecated, or rejected records it stops and directs you to draft a new record or use the supersede workflow instead of editing history.

Related Skills

Explore More Software Engineering Skills→
ccfccf

architecture-decision-records

Document architectural decisions with a MADR-style template and lifecycle.

Community
Advanced
atomicinnovationatomicinnovation
30

review-adr

Review ADR YAML frontmatter and enforce lifecycle status transitions.

Official
Advanced
rghsoftwarerghsoftware

ADR & Drift Review

Review ADRs for conflicts, broken supersede chains, and spec drift.

Official
Advanced
volodchenkovvolodchenkov
2

documentation-discipline

Guide developers on documenting code, APIs, and design decisions.

Community
Basic