skills.rest
RavitejaKarra24
RavitejaKarra24COMMUNITY
Explore all skills by this author →
𝕏@RavitejaKarra24GitHub

architecture-decision-records

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

Updated Mar 12, 2026
Search Tags:#architecture#documentation#adr#technical design#rfc#decision records#madr
One-click install
npx skills add https://github.com/RavitejaKarra24/dotfiles --skill architecture-decision-records-ravitejakarra24
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/RavitejaKarra24/dotfiles/tree/main/agents/.agents/skills/architecture-decision-records
Command: npx skills add https://github.com/RavitejaKarra24/dotfiles --skill architecture-decision-records-ravitejakarra24

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose track of why significant technical decisions were made, making it hard to onboard new members, review past choices, or avoid repeating mistakes. This Skill provides structured templates and processes for capturing the context, decision, and consequences of architectural choices. ## Core Features & Use Cases - Multiple ADR Templates: Standard MADR format, lightweight ADR, Y-Statement, deprecation records, and RFC-style proposals. - ADR Lifecycle Management: Track status from Proposed through Accepted, Deprecated, and Superseded, with directory structure and index conventions. - Review Process & Automation: Review checklists, best practices, and adr-tools CLI commands for creating, linking, and superseding records. - Use Case: When choosing PostgreSQL over MongoDB for a new service, generate a complete ADR documenting decision drivers, considered options, trade-offs, and migration consequences. ## Quick Start Write an ADR documenting our decision to adopt event sourcing for the order management service, including context, alternatives, 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 elements: context (why a decision was needed), the decision itself, and its consequences. Use the MADR template covering decision drivers, considered options with pros and cons, rationale, and positive and negative consequences.

When should I write an ADR versus skip it?▼

Write ADRs for significant choices like framework adoption, database selection, API design patterns, and security architecture. Skip them for minor version upgrades, bug fixes, routine maintenance, and configuration changes.

What is the difference between MADR and Y-Statement ADR formats?▼

MADR is a full template with context, decision drivers, options, and consequences sections. Y-Statement is a single structured sentence covering context, decision, alternatives, goals, and accepted downsides for lightweight documentation.

How do I deprecate or supersede an existing ADR?▼

Create a new ADR that references the old one and update the original's status to Deprecated or Superseded rather than editing it. With adr-tools, run adr new -s <number> to create a superseding record automatically.

Can adr-tools automate ADR management on macOS?▼

Yes, install adr-tools via Homebrew with brew install adr-tools. It supports adr init to set up the directory, adr new to create records, adr link to connect related decisions, and adr generate toc for the index.

Related Skills

Explore More Software Engineering Skills→
t-i-0414t-i-0414

project-context

Summarize project goals, constraints, and dependencies into a context document.

Community
Intermediate
miyake-sanmiyake-san

adr-skill

Create and maintain Architecture Decision Records with implementation plans for coding agents.

Community
Advanced
CuriousLearnerCuriousLearner
27

architecture-documenter

Document system architecture and technical decisions with diagrams and ADRs.

Community
Advanced
GomezFabricioGomezFabricio

rfc

Generate an RFC.md from context.md and an optional PRD.md using a template.

Community
Intermediate