doc-adr-reviewer_skill

Overview

This skill performs comprehensive content review and quality assurance for Architecture Decision Records (ADR). It checks decision completeness, alignment to BRD topics, consequence and alternative coverage, cross-references, naming, placeholders, and upstream drift. The skill produces a review score and a categorized issue list, and updates a mandatory drift cache used to detect stale upstream documents.

How this skill works

The reviewer loads one or more ADR files, enforces a nested-folder structure, and runs a suite of content checks including decision completeness, BRD mapping, consequence and alternative analysis, cross-reference integrity, naming rules, and placeholder detection. It extracts upstream references (for example @bdd tags and links to ../04_BDD/), computes SHA-256 hashes, compares them against a persistent .drift_cache.json, and flags content drift with severity thresholds. Reports, cache updates, and optional auto-fixes are saved alongside the ADR in the nested folder.

When to use it

• Immediately after ADR generation or autopilot runs to validate content quality
• After manual edits to an ADR to confirm decision rationale and links remain correct
• Before running system-generation or SYS-level automation to ensure ADRs are final
• During formal architecture review sessions as a final QA gate
• As part of periodic maintenance to detect upstream drift and stale decisions

Best practices

• Always store ADRs in the required nested folder format so checks can run
• Run the reviewer after any change to upstream BDD or PRD artifacts to detect drift early
• Address errors marked as blocking (structure and critical drift) before proceeding
• Keep the drift cache under source control or backed up to preserve audit history
• Treat reviewer warnings as actionable items: add mitigations, rationale, or links rather than ignoring them

Example use cases

• Validate that a newly generated ADR includes context, explicit decision, rationale, and date before approval
• Detect that a linked BDD feature changed substantially and flag the ADR for re-evaluation
• Find placeholders like [TODO] or [TBD] left in an ADR and list them for manual update
• Verify BRD Section 7.2 topics are covered and identify missing traceability entries
• Produce a review report with a PASS/WARNING/FAIL score before merging ADRs into the canonical docs