skills.rest
magnus919
magnus919COMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr-authoring

Document architectural decisions using ADR templates with lifecycle governance.

86|9|Updated Jun 5, 2026
Search Tags:#architecture#documentation#adr#governance#traceability#pyramid
One-click install
npx skills add https://github.com/magnus919/hermes-profiles --skill adr-authoring-magnus919
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-authoring
Source: https://github.com/magnus919/hermes-profiles/tree/main/skills/architecture/adr-authoring
Command: npx skills add https://github.com/magnus919/hermes-profiles --skill adr-authoring-magnus919

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Architecture Decision Records (ADRs) provide a structured approach to capture design decisions, their rationales, alternatives considered, and the consequences of choices. They map ADRs to the Artifact Pyramid layers (navigation index→L1, active ADRs→L2, superseded ADRs→L3) to support progressive disclosure and historical traceability. Use this skill when the technical-architect profile needs to document architectural decisions with clear governance and long-term maintainability.

Core Features & Use Cases

  • Template-driven ADR creation and governance guidance (Nygard, MADR, Tyree & Akerman, arc42, EdgeX, etc.).
  • Lifecycle management: proposing, accepting, superseding, and retiring ADRs with linked references.
  • Strong traceability: links to requirements, design artifacts, and related ADRs; aligns with C4 models.
  • Progressive disclosure via Artifact Pyramid: navigate from index to active decisions and dossiers.

Quick Start

Create a MADR ADR documenting your latest architectural decision and place it in the docs/adr/ directory with a clear title.

Frequently Asked Questions about adr-authoring

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

FAQPage Schema
What is an Architecture Decision Record and when do I need one?▼

An Architecture Decision Record (ADR) captures design decisions, rationales, alternatives considered, and consequences. You need ADRs when software engineering teams require structured governance, traceability to requirements, and long-term maintainability for architectural choices.

How do I document architectural decisions using MADR or Nygard templates?▼

Document architectural decisions by selecting a template like MADR, Nygard, Tyree & Akerman, or arc42, then capturing the decision rationale, options analysis, and lifecycle status. Place the completed ADR in your docs/adr/ directory with a clear title for governance.

How does the Artifact Pyramid map ADR lifecycle states for progressive disclosure?▼

The Artifact Pyramid maps ADR lifecycle states through progressive disclosure: navigation indexes sit at L1, active ADRs reside at L2, and superseded ADRs archive at L3. This structure provides historical traceability and supports progressive disclosure of architectural decisions over time.

Can I link ADRs to requirements and C4 design artifacts for traceability?▼

Yes, ADRs support strong traceability by linking directly to requirements, design artifacts, and related ADRs. The records align with C4 models, ensuring architectural decisions connect properly to existing software engineering documentation and code components.

What is the best way to manage superseding and retiring ADRs?▼

Manage superseding and retiring ADRs through lifecycle governance by creating linked references between the new and old records. Superseded ADRs move to the L3 layer of the Artifact Pyramid, maintaining clear historical traceability while the active decision takes the L2 position.

Does ADR governance work for multiple formats like arc42 and EdgeX?▼

ADR governance supports multiple formats including Nygard, MADR, Tyree & Akerman, arc42, and EdgeX. Template-driven creation provides structured options analysis and sustainability criteria evaluation across these formats, applicable to software engineering teams across diverse projects.

Related Skills

Explore More Software Engineering Skills→
sumilee-pcusumilee-pcu

create-epics

Translate game design documents into bounded architectural epics with ADRs and engine risks.

Community
Advanced
magnus919magnus919
86

artifact-pyramids

Map AI outputs into L1 Summary, L2 Analysis, and L3 Dossiers layers.

Community
Advanced
Pixel-Process-UGPixel-Process-UG
1

senior-architect

Guide system design, ADR creation, and scalability planning.

Official
Advanced
ekremmkasapekremmkasap

architecture-decision-records

Document architecture decisions with standardized ADR templates and lifecycle tracking.

Community
Advanced