reviewing-architecture-doc

Reviews finished architecture documents and linked ADR files against a 10-condition quality bar, emitting an approve or revise verdict.

1|1|Updated May 24, 2026
One-click install
npx skills add https://github.com/bm629/agent-skills --skill reviewing-architecture-doc-bm629
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: reviewing-architecture-doc
Source: https://github.com/bm629/agent-skills/tree/main/skills/reviewing-architecture-doc
Command: npx skills add https://github.com/bm629/agent-skills --skill reviewing-architecture-doc-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Architecture documents often look complete while hiding real gaps: decisions pasted inline instead of recorded as ADRs, NFR targets restated without realizing mechanisms, or diagrams that disagree with the prose. This Skill acts as an independent acceptance gate that judges a finished whole-system architecture document and its linked ADR files against a fixed 10-condition bar, so engineers can trust the doc before building within it. ## Core Features & Use Cases - 10-condition quality checklist: Judges boundary and external dependencies, component structure at whole-system altitude, diagram-narrative sync, the ADR mechanism (linked, immutable, one decision per file), traced and justified decisions, NFR realization, cross-cutting concerns, ASR coverage, and no fabricated claims. - Machine-parseable verdict: Emits exactly VERDICT: approve or VERDICT: revise plus actionable findings naming the failed condition, location, and concrete fix. - Delta-scoped amend reviews: Reviews only the changed decisions and their ripple when handed a change request against an approved doc, without re-judging the unchanged architecture. - Use Case: After authoring a system architecture doc with linked ADR files, run this Skill as the review gate; it flags that the datastore decision is embedded inline instead of a linked ADR and tells the author exactly how to fix it before approval. ## Quick Start Use reviewing-architecture-doc to judge docs/architecture.md together with its linked adr/ files and give me the verdict with actionable findings.

Frequently Asked Questions about reviewing-architecture-doc

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

FAQPage Schema
How do I review a software architecture document before approving it?

Hand the finished architecture doc and its linked ADR files to this Skill, which judges them against a 10-condition bar covering boundaries, structure, decisions, NFRs, and cross-cutting concerns. It emits VERDICT: approve or VERDICT: revise with actionable findings for each gap.

What makes an architecture decision record review fail?

The ADR mechanism fails when a significant decision is pasted inline instead of recorded as a standalone linked ADR, when one ADR bundles two decisions, when the index is out of sync with the files, or when an accepted ADR is edited in place instead of superseded by a new one.

Can this review an architecture doc without the ADR files?

It can review the doc, but condition 4 (the ADR mechanism) is unverifiable without the linked ADR files. The reviewer flags that condition as unverifiable rather than fabricating ADR content or guessing at index sync.

Does it require a specific framework like C4 or arc42?

No. C4, arc42, ATAM, and 4+1 are treated as authoring techniques judged by outcome, never as mandatory conditions. The review checks whether the boundary is drawn, decisions are linked and traced, and NFR targets are realized, regardless of which framework produced them.

When should I use design-review instead of this Skill?

Use design-review for generic engineering design docs, RFCs, standalone ADRs, specs, and plans. This Skill is the dedicated gate for the doc-library architecture-doc artifact identified by its template frontmatter, plus its linked ADR files.

Will a short architecture doc for a small system fail review?

No. The bar is proportional: a thin system legitimately omits deployment views, messaging, or a changelog, and collapsed sections are not gaps. A revise verdict requires a real, named deficiency such as an unnamed external dependency or a restated NFR target with no mechanism.