How do I install the Architectural Review skill?

Run npx skillmds@latest add pngdeity/architectural-review in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Architectural Review safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Architectural Review?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Architectural Review free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Architectural Review?

pngdeity (@pngdeity) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Architectural Review by pngdeity — Agent Skill

Name: Architectural Review
Author: pngdeity

Architectural Review

Workflow for writing and auditing Architecture Decision Records (ADR) and Technical Design Documents (TDD). Use when creating new architectural decisions or reviewing functional designs for correctness and logic. Not for modifying existing skills, performing code reviews, or implementing code changes.

pngdeity Updated Sep 17, 2026

File contents

Architectural Review Skill

This skill enforces high-fidelity architectural and technical documentation standards. It provides a structured workflow for drafting and auditing ADRs and TDDs.

Workflow: Drafting Documentation

When tasked with writing an ADR or TDD, follow the schemas defined in references/schemas.md.

Information Gathering: Identify all "Decision Drivers" and "Alternatives Considered."
Drafting: Use imperative mood and scannable tables/bullets.
Verification: Ensure mandatory sections (like "Alternatives Considered" for ADRs) are present.

Workflow: The 3-Phase Audit

When tasked with reviewing an existing document, perform this exhaustive audit:

Phase 1: Structural Audit

Checklist: Verify all required sections from references/schemas.md are present.
Grading: Mark as [Fail] if the "Alternatives Considered" section is missing or if the "Interface Contract" lacks strict types.
- If structural audit fails: Stop and report the missing sections. Do not proceed to Phase 2 until the document structure is corrected.

Phase 2: Logic & Soundness Audit

Blast Radius: Evaluate the impact of the decision on other system components.
Complexity: Identify potential "Gold Plating" or over-engineering.
Security: Check for "Fail Securely" violations and PII leakage.
Pure Function Test (TDD Only): Verify if the module is truly atomic and side-effect-free.

Phase 3: Consistency Report

Lineage: Ensure the document correctly references parent ADRs or related TDDs.
Drift: Identify if the proposed design contradicts existing mandates in GEMINI.md.

Final Output Format

Deliver your review document-by-document. For each document, provide:

A [Pass/Fail] grade for Structure and Logic.
Detailed feedback and actionable fixes.
The Phase 3 Consistency Report.

Verification

Verify this skill produces correct output:

Create a fixture ADR document with a missing "Alternatives Considered" section.
Run the 3-Phase Audit against it.
Confirm the Structural Audit returns [Fail] and correctly identifies the missing section.
Create a fixture TDD with all required sections present. Confirm it passes Phase 2 logic audit.

---name: architectural-reviewdescription: Workflow for writing and auditing Architecture Decision Records (ADR) and Technical Design Documents (TDD). Use when creating new architectural decisions or reviewing functional designs for correctness and logic. Not for modifying existing skills, performing code reviews, or implementing code changes.---# Architectural Review SkillThis skill enforces high-fidelity architectural and technical documentation standards. It provides a structured workflow for drafting and auditing ADRs and TDDs.## Workflow: Drafting DocumentationWhen tasked with writing an ADR or TDD, follow the schemas defined in [references/schemas.md](references/schemas.md).1. **Information Gathering:** Identify all "Decision Drivers" and "Alternatives Considered."2. **Drafting:** Use imperative mood and scannable tables/bullets.3. **Verification:** Ensure mandatory sections (like "Alternatives Considered" for ADRs) are present.## Workflow: The 3-Phase AuditWhen tasked with reviewing an existing document, perform this exhaustive audit:### Phase 1: Structural Audit- **Checklist:** Verify all required sections from [references/schemas.md](references/schemas.md) are present.- **Grading:** Mark as `[Fail]` if the "Alternatives Considered" section is missing or if the "Interface Contract" lacks strict types. - **If structural audit fails:** Stop and report the missing sections. Do not proceed to Phase 2 until the document structure is corrected.### Phase 2: Logic & Soundness Audit- **Blast Radius:** Evaluate the impact of the decision on other system components.- **Complexity:** Identify potential "Gold Plating" or over-engineering.- **Security:** Check for "Fail Securely" violations and PII leakage.- **Pure Function Test (TDD Only):** Verify if the module is truly atomic and side-effect-free.### Phase 3: Consistency Report- **Lineage:** Ensure the document correctly references parent ADRs or related TDDs.- **Drift:** Identify if the proposed design contradicts existing mandates in `GEMINI.md`.## Final Output FormatDeliver your review document-by-document. For each document, provide:1. A `[Pass/Fail]` grade for Structure and Logic.2. Detailed feedback and actionable fixes.3. The Phase 3 Consistency Report.## VerificationVerify this skill produces correct output:1. Create a fixture ADR document with a missing "Alternatives Considered" section.2. Run the 3-Phase Audit against it.3. Confirm the Structural Audit returns `[Fail]` and correctly identifies the missing section.4. Create a fixture TDD with all required sections present. Confirm it passes Phase 2 logic audit.

Frequently asked questions