Architecture Decision

Architecture Decision

argument-hint: "[title] [--review full|lean|solo]"

Category: content-creation Source: Donchitos/Claude-Code-Game-Studios

Architecture Decision Skill

What Is This?

The Architecture Decision skill for the Happycapy Skills platform is a content-creation tool designed to streamline the documentation of significant technical choices in your software projects. When invoked, it generates an Architecture Decision Record (ADR), which captures the rationale behind a major architectural decision, the context in which it was made, alternative options considered, and the potential consequences of the selection. This ensures that every key technical direction taken in a project is transparent, traceable, and easy to review for current and future team members.

The skill is user-invocable and supports several modes of operation, including normal creation of new ADRs and a specialized retrofit mode for upgrading or validating existing ADR files. It leverages both interactive and automated workflows, supporting command-line arguments that tailor its behavior, such as the level of review detail (--review full, --review lean, --review solo). The skill integrates with the Happycapy platform’s tooling ecosystem, including file reading, writing, and user prompts.

Why Use It?

Documenting architecture decisions is a best practice in modern software engineering. Projects often span many months or years, with team members rotating in and out. Without systematic recording of why certain paths were chosen, teams risk repeating mistakes, losing critical context, or making incompatible changes. ADRs act as a living history of your technical decision-making process.

The Architecture Decision skill automates and standardizes ADR creation, reducing friction and ensuring all essential sections are included. This minimizes the risk of missing key information such as status, dependencies, and compatibility notes. By enforcing a template and validating presence of required sections, the skill helps maintain high-quality documentation, which is critical for onboarding, audits, and ongoing architectural integrity.

Moreover, the skill’s retrofit mode allows teams to upgrade existing ADR files to meet evolving documentation standards without starting from scratch. It can detect missing sections, highlight gaps, and ensure all ADRs meet the latest team or organizational requirements.

How to Use It

Basic Invocation

To create a new ADR, invoke the skill with a title and (optionally) a review mode:

architecture-decision "Adopt Event-Driven Architecture" --review full
  • The --review argument can be set to full, lean, or solo, determining how thorough the review and documentation process will be.
  • If --review is not provided, the skill checks the production/review-mode.txt file for a default value, or defaults to lean if no setting is found.

Retrofit Mode

To validate or upgrade an existing ADR file, use the retrofit argument followed by the file path:

architecture-decision retrofit docs/architecture/adr-0001-event-system.md

In retrofit mode, the skill reads the ADR file, scans for required sections (such as ## Status, ## ADR Dependencies, etc.), and reports which sections are present or missing. Missing sections are flagged according to their importance, for example:

  • Missing ## Status is BLOCKING (the ADR cannot be properly reviewed or accepted).
  • Missing ## ADR Dependencies or ## Engine Compatibility are HIGH priority gaps.

This helps teams bring older ADRs up to current standards efficiently.

Typical ADR Template Example

Here is a simplified example of the ADR template the skill uses:

## [ADR Title]

## Status
Proposed

## Context
Describe the problem or motivation for this decision.

## Decision
State the chosen solution.

## Consequences
List the consequences, positive and negative, of this decision.

## ADR Dependencies
Reference related ADRs if applicable.

## Engine Compatibility
Note any engine or platform compatibility considerations.

## GDD Requirements Addressed
Map to Game Design Document requirements, if relevant.

When the skill is invoked, it generates a file with these sections, prompting the user for required input when needed.

When to Use It

Use the Architecture Decision skill every time your team makes a major technical or architectural choice, such as:

  • Selecting a new framework, library, or tool
  • Changing a core data model or service interface
  • Adopting or rejecting a design pattern
  • Making decisions that impact system scalability, performance, or maintainability

Additionally, use retrofit mode when you need to audit or upgrade ADRs to comply with new standards, or when integrating legacy documentation into a unified system.

Important Notes

  • Section Completeness: The skill enforces the presence of essential ADR sections. Missing critical sections (like ## Status) are flagged as blocking, ensuring that incomplete records cannot be accidentally approved.
  • Review Modes: The review mode controls the depth of documentation and validation, supporting workflows from solo authoring to full team review.
  • Traceability: By linking ADRs to dependencies and GDD requirements, the skill ensures architectural decisions remain connected to design and implementation goals.
  • Platform Integration: The skill supports file reading, writing, and user interaction, making it suitable for both interactive and automated pipelines.

In summary, the Architecture Decision skill brings rigor, consistency, and traceability to your technical decision-making process, helping teams maintain high-quality documentation and architectural coherence at every stage of development.