architecture-decision

Document Architecture Decision Records with context, alternatives, and consequences.

Updated Apr 10, 2026

Search Tags:#architecture #documentation #adr #governance #traceability

Ready to run

npx skills add https://github.com/emcconnell/nova-scout --skill architecture-decision-emcconnell

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architecture-decision
Source: https://github.com/emcconnell/nova-scout/tree/main/.claude/skills/architecture-decision
Command: npx skills add https://github.com/emcconnell/nova-scout --skill architecture-decision-emcconnell

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ADRs provide a formal, traceable record of significant technical decisions, capturing context, trade-offs, and expected consequences to guide future work and onboarding.

Core Features & Use Cases

ADR authoring: Create, update, and reference Architecture Decision Records to document rationale, alternatives, and outcomes.
Template-driven consistency: Generate ADR templates that follow project conventions for uniformity across the codebase.
Governance & traceability: Link ADRs to related design documents, tickets, and design goals to ensure alignment and maintainability.

Quick Start

Draft a complete ADR for the given architectural decision using the project context and guidelines.

Frequently Asked Questions about architecture-decision

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

FAQPage Schema

How do I document an Architecture Decision Record with alternatives and consequences?▼

To document an Architecture Decision Record, draft the problem statement, constraints, alternatives, and consequences. This ensures the ADR captures context and trade-offs to guide future development and maintain traceability.

What should be included in an ADR template for software architecture governance?▼

An ADR template for architecture governance should include the problem statement, constraints, rationale, risks, and a migration or verification plan. This provides a formal, traceable record of significant technical decisions for onboarding.

When do I need to create an Architecture Decision Record for a technical decision?▼

You need to create an Architecture Decision Record when a technical decision is significant enough to require formal traceability. Documenting the decision captures expected outcomes and trade-offs to align future work with design goals.

Can ADRs be linked to existing design documents and project tickets for traceability?▼

Yes, ADRs can be linked to existing design documents and project tickets. Linking these elements ensures architecture governance, maintains alignment across the codebase, and provides clear traceability for technical decisions.

What is the best way to maintain consistency when writing architecture documentation across a codebase?▼

The best way to maintain consistency in architecture documentation is using a template-driven approach for ADR authoring. Generating ADRs that follow project conventions ensures uniformity and clear documentation of rationale across the codebase.

Does writing an Architecture Decision Record require detailing a migration plan?▼

Yes, writing an Architecture Decision Record requires detailing a migration or verification plan. Including this plan alongside the problem statement and risks ensures the ADR produces a complete draft for technical governance.