skills.rest
OKHP3
OKHP3COMMUNITY
Explore all skills by this author →
WebsiteGitHub

architecture-decision-records

Write and maintain Architecture Decision Records documenting technical decisions, trade-offs, and consequences.

1|Updated Jun 13, 2026
Search Tags:#architecture#documentation#adr#decision records#technical decisions#MADR#adr-tools
One-click install
npx skills add https://github.com/OKHP3/refoldec --skill architecture-decision-records-okhp3
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/OKHP3/refoldec/tree/main/.agents/skills/architecture-decision-records
Command: npx skills add https://github.com/OKHP3/refoldec --skill architecture-decision-records-okhp3

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose the context and rationale behind significant technical decisions over time, making it hard to review past choices, onboard new members, or avoid repeating mistakes. This Skill provides structured templates and processes for capturing architectural decisions as durable records. ## Core Features & Use Cases - Multiple ADR Templates: Includes MADR format, lightweight ADRs, Y-Statements, deprecation records, and RFC-style proposals. - Lifecycle Management: Covers ADR statuses (Proposed, Accepted, Deprecated, Superseded, Rejected), directory structure, index generation, and adr-tools automation. - Review Process: Provides checklists for pre-submission, review, and post-acceptance steps. - Use Case: When choosing between PostgreSQL, MySQL, and MongoDB for a new platform, use this Skill to produce a complete ADR documenting context, decision drivers, considered options, rationale, and consequences. ## Quick Start Write an Architecture Decision Record for adopting PostgreSQL as the primary database, including context, considered options, and consequences.

Frequently Asked Questions about architecture-decision-records

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

FAQPage Schema
How do I write an Architecture Decision Record?▼

An ADR captures three core elements: context (why a decision was needed), the decision itself, and its consequences. Use the MADR template to document decision drivers, considered options with pros and cons, rationale, and positive and negative outcomes.

When should I write an ADR versus skip it?▼

Write an ADR for significant decisions like framework adoption, database technology choices, API design patterns, and security architecture. Skip ADRs for minor version upgrades, bug fixes, implementation details, and routine configuration changes.

What ADR format should I use for my team?▼

Use the MADR format for thorough documentation of major decisions, the lightweight template for quick choices, Y-Statements for concise one-paragraph records, and RFC style for proposals needing broad feedback before acceptance.

How do I deprecate or supersede an existing ADR?▼

Never edit an accepted ADR; instead write a new ADR that supersedes it, update the old record's status to Deprecated or Superseded, and link both records. The deprecation template includes migration phases and lessons learned sections.

Can I automate ADR creation with adr-tools?▼

Yes, adr-tools supports initializing an ADR directory, creating numbered records with adr new, superseding old records with adr new -s, generating a table of contents, and linking related ADRs bidirectionally.

Related Skills

Explore More Software Engineering Skills→
BEIRUXBEIRUX

doc-coauthoring

Guide collaborative drafting of technical specs, proposals, and decision records.

Official
Intermediate
sortie-aisortie-ai
121

managing-adrs

Create and validate MADR 4.0 Architecture Decision Records with required frontmatter.

Official
Advanced
act70255act70255

architecture-decision-records

Manage the creation, documentation, and lifecycle of Architecture Decision Records.

Community
Advanced
govctl-orggovctl-org
239

quick

__init__

Official
Basic