skills.rest
onemanking
onemankingCOMMUNITY
Explore all skills by this author →
GitHub

architecture-decision

Generates numbered Architecture Decision Records documenting technical decisions, alternatives, and consequences.

Updated Apr 13, 2026
Search Tags:#architecture#documentation#markdown#decision record#adr#software architecture#technical design
One-click install
npx skills add https://github.com/onemanking/the-operator --skill architecture-decision-onemanking
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision
Source: https://github.com/onemanking/the-operator/tree/main/.github/skills/architecture-decision
Command: npx skills add https://github.com/onemanking/the-operator --skill architecture-decision-onemanking

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often make significant technical decisions without documenting the reasoning, alternatives, and trade-offs, leaving future maintainers guessing why the system was built a certain way. This Skill produces a consistent, numbered Architecture Decision Record (ADR) for every major technical choice. ## Core Features & Use Cases - Automatic ADR numbering: Scans docs/architecture/ to determine the next ADR number so records stay sequential. - Structured ADR template: Generates a complete record covering status, context, constraints, decision, alternatives considered, consequences, performance implications, migration plan, and validation criteria. - Context gathering: Reads related code and existing ADRs, and asks clarifying questions when the title alone is insufficient. - Use Case: After deciding to replace a REST layer with an event-driven message bus, invoke the Skill to produce docs/architecture/adr-0007-event-driven-messaging.md capturing the rejected alternatives and migration plan. ## Quick Start Ask the assistant to create an architecture decision record for your chosen technical decision, providing a short title such as "adopt event-driven messaging".

Frequently Asked Questions about architecture-decision

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

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

Invoke the Skill with a short title for the decision. It scans docs/architecture for existing ADRs to assign the next number, gathers context from related code, and writes a structured Markdown ADR file.

What should an ADR document include?▼

An ADR should include status, date, problem statement, constraints, requirements, the decision itself, alternatives considered with rejection reasons, consequences, risks, performance implications, a migration plan, and validation criteria.

Where are ADR files stored in a repository?▼

This Skill saves ADRs to docs/architecture/ using the naming pattern adr-[NNNN]-[slug].md, where the number is determined by scanning existing records in that directory.

When should I write an ADR instead of a code comment?▼

Write an ADR for significant technical decisions that affect system structure, interfaces, or long-term maintenance. Code comments suit local implementation details, while ADRs capture cross-cutting choices and their trade-offs.

Can an ADR be changed after it is accepted?▼

ADRs are generally immutable once accepted. Instead of editing, create a new ADR with status Superseded referencing the original, preserving the decision history and rationale over time.

Related Skills

Explore More Software Engineering Skills→
KentoShimizuKentoShimizu
7

documentation-rfc

Draft decision-ready RFCs with problem statements, options, constraints and risk assessment for stakeholder sign-off.

Community
Advanced
JDenn0514JDenn0514
1

describe-design

Generate architectural documentation with Mermaid diagrams and stable code references.

Community
Advanced
staticalandstaticaland
4

grill-with-docs

Interviews a plan or design and generates ADRs and glossary documentation.

Community
Basic
girijashankarjgirijashankarj
28

adr-generator

Document architecture decisions using the Michael Nygard ADR format.

Community
Advanced