skills.rest
DeepSpaceCartel
DeepSpaceCartelOFFICIAL
Explore all skills by this author →
WebsiteGitHub

adr

Write and maintain Architecture Decision Records using numbered Markdown files.

Updated Sep 9, 2026
Search Tags:#documentation#markdown#adr#software architecture#decision log#architecture decision record
One-click install
npx skills add https://github.com/DeepSpaceCartel/skills --skill adr-deepspacecartel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/DeepSpaceCartel/skills/tree/main/skills/adr
Command: npx skills add https://github.com/DeepSpaceCartel/skills --skill adr-deepspacecartel

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architectural decisions get made and then forgotten, leaving future maintainers to reconstruct the reasoning from git history and chat logs. This Skill provides a structured convention for recording each significant decision, its context, and its consequences in a permanent, greppable decision log. ## Core Features & Use Cases - Numbered File Convention: Stores ADRs as zero-padded, sequentially numbered files (docs/decisions/NNNN-title.md) that are never reused, so references like ADR-0007 always resolve. - Nygard Template: Applies Michael Nygard's Status/Context/Decision/Consequences structure, with status values from proposed through superseded. - Supersede Instead of Edit: Guides writing a new ADR that supersedes an outdated one, with bidirectional linking, preserving decision history. - Use Case: When choosing between a monolith and microservices, create ADR-0005 capturing the constraints, the chosen approach, rejected alternatives, and the trade-offs accepted. ## Quick Start Write an ADR for the decision to adopt PostgreSQL as the primary database, following the standard template and numbering convention.

Frequently Asked Questions about adr

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

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

Create a numbered Markdown file like docs/decisions/0001-use-postgres.md with Status, Context, Decision, and Consequences sections. State the decision as an active commitment, explain the forces behind it, and honestly list the trade-offs it introduces.

When is a decision worth writing an ADR for?▼

Write an ADR for choices with lasting downstream cost: database selection, cross-cutting patterns like monolith versus services, dropping supported features, or security-relevant trade-offs. Skip easily reversible choices like variable names or linter configs.

Should I edit an old ADR when the decision changes?▼

No. Write a new ADR that supersedes the old one, set the old ADR's status to superseded by ADR-NNNN, and link both records to each other. Editing history defeats the purpose of keeping a decision log.

What status values can an ADR have?▼

An ADR can be proposed, accepted, deprecated, or superseded by ADR-NNNN. Proposed means under discussion, accepted is the current decision, deprecated means no longer recommended, and superseded points to the replacing ADR.

How do I reference an ADR from code or pull requests?▼

Link by number, for example a comment like // see ADR-0003 in the implementing code, commit, or PR. Numbers are never reused, so the reference stays stable and greppable even after the ADR is superseded.

Related Skills

Explore More Software Engineering Skills→
phuthuycodingphuthuycoding
10

spike

Run a time-boxed spike workflow with research, prototyping, and evaluation phases.

Community
Basic
abdullah1854abdullah1854
1

frontend-build

Generate Markdown ADRs with sections and auto-assigned numbers from structured inputs.

Community
Advanced
gensart-projsgensart-projs

architecture

Document architectural decisions using structured ADR templates and checklists.

Community
Advanced
scanadyscanady

tech-arch-architecture-decision-records

Create and index Architecture Decision Records using MADR and other templates.

Community
Advanced