Architecture decision records

Skill yeaight7/agent-powerups/plugins/documentation-systems/skills/architecture-decision-records

Use when a significant architectural choice is being finalized, revisited, or reversed -- technology selection, structural patterns, or trade-offs that future maintainers or agents might unknowingly undo.From its SKILL.md

Install

npx -y skills add yeaight7/agent-powerups --skill architecture-decision-records

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.9 KB, 636 tokens by cl100k_base, as published. Nobody here has run it

Purpose

Code tells you how a system works. ADRs tell you why it works that way, preventing future maintainers (and AI agents) from suggesting "improvements" that were already tried and discarded.

When to Use

Finalizing a major design decision (e.g., "Choosing Postgres over MongoDB", "Using custom event bus over Redis")
Reversing or superseding a previous decision
A reviewer or agent proposes a change that contradicts an existing constraint

Inputs

The decision, the alternatives considered, and the constraints that drove it
The ADR directory (conventionally docs/adr/)

Workflow

Check for an existing ADR first — the decision may already be recorded or superseded:

ls docs/adr/                          # existing records
rg -ln "<topic keyword>" docs/adr/    # is this decision already covered?

Create the record at docs/adr/YYYY-MM-DD-<short-title>.md — date-prefixed for ordering, kebab-case title.

Fill the structure — keep it under 300 words; focus on constraints, not theory:

# <Decision title>

## Status
Accepted | Superseded by <newer ADR filename>

## Context
What is the problem? What constraints apply?

## Decision
What are we doing?

## Consequences
What trade-offs are we accepting? What becomes harder?

Handle supersession explicitly. When reversing a decision, do NOT edit history: write a new ADR, mark the old one "Superseded by" with a link to the new file, and state what changed.
Link from where the decision bites — a one-line pointer near the affected module or in the architecture doc, so the why is discoverable from the how.

Output

A dated ADR file with Status / Context / Decision / Consequences
Superseded ADRs updated with forward links — never deleted or rewritten

Verification

File saved under docs/adr/ with a date-prefixed kebab-case name
Status, Context, Decision, and Consequences sections all present; body under ~300 words
Consequences state real trade-offs, not just benefits
Superseded decisions marked and forward-linked, not edited or removed
Decision discoverable from the affected code or architecture doc

Failure Modes

Retroactive rewriting — editing an old ADR to match a new decision destroys the historical why; supersede instead.
Theory essays — pages of architecture philosophy nobody reads; constraints fit in 300 words.
Consequence-free records — a Decision without trade-offs is advocacy, not a record.
Orphaned ADRs — records nobody can find from the code they govern.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most architecture codebase skills give in 636 tokens

Counted across 811 of the 1,134 authors here whose files we hold, read 2026-08-07

Ask the user which candidate to explorein 45 of 811, across 15 files
Apply the deletion test to suspected shallow modulesin 43 of 811, across 15 files
Read any relevant architecture decision records firstin 31 of 811, across 8 files
Use exact glossary terms in every suggestionin 30 of 811, across 10 files
Accept dependencies instead of creating themin 24 of 811, across 5 files
Include before and after visualisations for each candidatein 24 of 811, across 5 files
Read the domain glossary before exploringin 24 of 811, across 6 files
Return results instead of producing side effectsin 23 of 811, across 4 files
Explore the codebase for shallow modules and frictionin 23 of 811, across 3 files
Introduce seams only where things varyin 22 of 811, across 3 files
Reduce the number of methodsin 21 of 811, across 2 files
Design deep modules with small interfacesin 21 of 811, across 3 files

Said here and by no other author read

Fill the specified markdown structure.
Keep the record body under 300 words.
State real trade-offs in the Consequences section.
Mark old records as Superseded when reversing a decision.
Link the record from the affected code or documentation.

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.