architecture-review

Reviews an existing system's architecture adversarially against its actual source code and ADRs.

3|Updated Feb 18, 2026
One-click install
npx skills add https://github.com/gener8v/gener8v.claude-skills --skill architecture-review-gener8v
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-review
Source: https://github.com/gener8v/gener8v.claude-skills/tree/main/skills/architecture-review
Command: npx skills add https://github.com/gener8v/gener8v.claude-skills --skill architecture-review-gener8v

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architecture documentation often drifts from what the code actually does, and locally reasonable decisions can compose into a system that is structurally wrong for its purpose. This Skill pressure-tests an existing system's architecture against the running code, exposing doc-to-code gaps, mis-invested effort, and deferred existential risks. ## Core Features & Use Cases - Reality Audit: Verifies every Accepted ADR in the source and confirms Proposed items are genuinely unbuilt, distinguishing substance from stubs with line counts and test counts. - Adversarial Theses: Develops 2-4 code-cited theses on whether a system of this nature should be designed this way, each with inherent limitations, concrete better-decision sketches, and steelmans. - Structured Report: Writes a point-in-time assessment to .gener8v/reviews/<system-slug>-architecture-assessment.md with verdict, limitations, recommendations, and open questions. - Use Case: Before adopting a workflow engine, run the review on your pipeline system; it may reveal that most persistence code is irreducible domain logic, while the real finding is an over-built DAG engine running a strictly linear pipeline. ## Quick Start Run the architecture review on the ingestion system with focus on the tenancy model and job queue, and write the assessment report.

Frequently Asked Questions about architecture-review

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

FAQPage Schema
How do I review whether a system's architecture matches its code?▼

Verify each Accepted architecture decision record directly in the source rather than trusting documentation, and grep to confirm Proposed items are genuinely unbuilt. Distinguish substance from stubs using line counts, real function behavior, and test counts including skips.

What is the difference between architecture review and code review?▼

Architecture review operates at system altitude, questioning whether the overall design fits the nature of the system, while code review examines a single delivered ticket. Architecture review critiques ADRs, control planes, and risk sequencing; code review checks per-delivery implementation quality.

When should I run an architecture assessment on a codebase?▼

Run it during technical due diligence, before a major architectural commitment like adopting a datastore or workflow engine, when many ADRs have accumulated, or at milestone boundaries. It requires existing code; it is not for forward-looking design.

Can architecture review recommend adopting tools like Kafka or Temporal?▼

Only if the claim is proven against the actual codebase, showing the specific lines and failure modes it would replace plus honest new costs. Reflexive vendor recommendations without code evidence are explicitly rejected and retracted.

Why does a re-run of the architecture assessment drop previous findings?▼

Re-runs replace the report file at the same system slug, so the previous assessment must be read first and each thesis carried forward as addressed, still open, or retracted. Using a different slug starts a separate assessment instead of revising.