Architecture Review

Architecture Review

argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path/to/gdd.md]"

Category: design Source: Donchitos/Claude-Code-Game-Studios

Architecture Review

What Is This

The Architecture Review skill (architecture-review) for the Happycapy Skills platform provides a rigorous, automated process for validating the completeness and consistency of a project's architectural decisions against all Game Design Documents (GDDs). It serves as a critical technical gate, ensuring that every technical requirement from the design phase is both covered and implemented correctly before a project advances from Technical Setup to Pre-Production.

The skill operates by constructing a traceability matrix that maps each GDD technical requirement to one or more Architectural Decision Records (ADRs). It systematically detects coverage gaps (missing ADRs), uncovers cross-ADR conflicts, verifies that all decisions are consistent with the project's chosen engine version, and produces a clear verdict of PASS, CONCERNS, or FAIL. This makes it the architectural equivalent of a thorough design review and brings engineering discipline to the pre-production process.

Why Use It

Using the Architecture Review skill brings several key benefits to any game development workflow:

  • Comprehensive Coverage: It guarantees that no GDD technical requirement is forgotten or left unaddressed in the architecture, reducing the risk of late-stage surprises.
  • Consistency and Conflict Detection: By automatically analyzing ADRs for cross-references and contradictions, it helps teams avoid subtle integration issues that could otherwise derail projects.
  • Engine Compatibility Assurance: It checks that all architectural decisions are aligned with the specified engine version, preventing accidental drift or engine misuse.
  • Traceability and Accountability: The requirements traceability matrix links requirements to decisions, story files, and test files, making it easy to audit and evolve both design and implementation.
  • Actionable Verdicts: The PASS/CONCERNS/FAIL output gives clear direction to teams, highlighting exactly where attention is needed.

This skill is especially useful for technical directors, leads, and engineering managers who are responsible for maintaining architectural quality and project coherence.

How to Use It

The Architecture Review skill is invoked by calling architecture-review with one of several argument modes. Each mode targets a different aspect of the architectural review process:

Argument Modes

  • No argument or full: Executes the full review, including coverage, consistency, engine compatibility, and traceability checks.

  • coverage: Focuses exclusively on coverage. It identifies which GDD requirements do not have corresponding ADRs, producing a gap report.

  • consistency: Scans all ADRs for conflicting decisions or incompatible dependencies, reporting on cross-ADR conflicts.

  • engine: Checks that all ADRs are consistent with, and explicitly support, the project's pinned engine version.

  • single-gdd [path]: Limits the coverage review to a single GDD file, useful for incremental or modular reviews.

  • rtm: Generates an extended requirements traceability matrix, including GDD requirements mapped to ADRs, story files, and test files. Outputs to docs/architecture/requirements-traceability.md.

Example Usage

## Full architecture review
happycapy skill architecture-review

## Coverage only
happycapy skill architecture-review coverage

## Consistency only
happycapy skill architecture-review consistency

## Engine compatibility check
happycapy skill architecture-review engine

## Review a single GDD
happycapy skill architecture-review single-gdd path/to/gdd.md

## Generate requirements traceability matrix
happycapy skill architecture-review rtm

Output

The skill provides a verdict (PASS, CONCERNS, or FAIL) and detailed findings for each check. For example:

[ARCHITECTURE REVIEW] RESULT: CONCERNS
- Missing ADR for GDD requirement GDD-5.2 ("Asynchronous multiplayer lobby")
- Cross-ADR conflict: ADR-12 (network layer) vs ADR-18 (session management)
- Engine version mismatch: ADR-15 refers to Unity 2021, project pinned to Unity 2022

The rtm mode produces a Markdown-formatted matrix that can be committed to version control.

When to Use It

Use the Architecture Review skill at all major architectural milestones, especially:

  • Before Pre-Production: As a final check after Technical Setup, before any large-scale implementation begins.
  • After Major GDD Updates: Whenever the game design documents are significantly revised.
  • After Architectural Refactoring: When substantial changes are made to ADRs or when new technical directions are adopted.
  • During Quality Gates: As part of regular quality assurance processes to ensure ongoing architectural integrity.

Running the skill regularly helps catch issues early, ensuring that the architecture remains tightly aligned with evolving requirements.

Important Notes

  • The Architecture Review skill is strict: all GDD requirements must be traced to at least one ADR, and all ADRs must be internally consistent and engine-compatible.
  • It is user-invocable, meaning it can be run on-demand by anyone with access, but is best integrated into CI/CD pipelines for maximum effect.
  • Any findings of CONCERNS or FAIL should be taken seriously and addressed before advancing the project.
  • The skill relies on well-structured GDDs and ADRs. Poor documentation quality will reduce the effectiveness of the review.
  • The generated requirements traceability matrix (rtm mode) is a valuable artifact for audits, onboarding, and maintenance.
  • This skill does not perform code-level implementation checks; it is focused on architectural documentation and decisions.

By integrating the Architecture Review skill into your workflow, you ensure robust, transparent, and traceable architectural quality from the earliest stages of your game development project.