skills.rest
watchthelight
watchthelightCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr

Drafts MADR architecture decision records with micro-brainstorm scoring and pre-mortem analysis.

Updated Sep 3, 2026
Search Tags:#brainstorming#adr#design documentation#mkdocs#architecture decision record#madr#pre-mortem
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill adr-watchthelight
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/adr
Command: npx skills add https://github.com/watchthelight/shatterfish --skill adr-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering decisions are often made informally and forgotten, making it impossible to know why a design was chosen or what alternatives were rejected. This Skill enforces a disciplined decision process and produces a permanent, indexed record for every architectural choice. ## Core Features & Use Cases - Structured micro-brainstorm: Generates at least five options using CIS techniques (first principles, inversion, SCAMPER, analogies) and scores each against the project's non-negotiables. - MADR record writing: Creates a numbered ADR file in docs/adr/ with context, decision drivers, considered options, outcome, consequences, and a pre-mortem section. - Documentation integration: Updates docs/adr/index.md, adds the MkDocs nav entry, and links the ADR from related story specs. - Use Case: When deciding how the bot's Observer class should expose game state, invoke the skill to brainstorm five interface designs, score them against the information-parity rule, and record the chosen approach as ADR-0005. ## Quick Start Ask the assistant to write an ADR for the decision you just made, describing the question and constraints in one or two sentences.

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?▼

State the question in one sentence, brainstorm at least five options, score each against your project's decision drivers, pick one, and run a pre-mortem. Then write the record using the MADR template with context, options, outcome, and consequences sections.

What is the MADR template for ADRs?▼

MADR (Markdown Architecture Decision Records) uses sections for context and problem statement, decision drivers, considered options, decision outcome, and consequences. This skill adds a pre-mortem section and YAML frontmatter with status, date, and deciders.

When should I create an ADR instead of just coding?▼

Create an ADR for every design decision, including small ones, especially anything touching core interfaces, fairness rules, threading, or search. The record prevents reopening settled decisions without new information.

Can an accepted ADR be edited or reversed?▼

An accepted ADR is never edited except to change its status field. A change of mind requires writing a new ADR that supersedes the old one, preserving the full decision history.

How many options should an ADR consider?▼

At least five options should be generated using techniques like first principles, inversion, SCAMPER, and analogies from similar systems. Each option gets a one-line keep-or-reject rationale scored against the decision drivers.

Related Skills

Explore More Software Engineering Skills→
BRANDNEWSHVTBRANDNEWSHVT

brainstorming

Clarify design problems and requirements before implementation.

Official
Advanced
DexploarerDexploarer
7

ADR Assistant

Automate creation, analysis, and maintenance of Architecture Decision Records.

Community
Intermediate
co-cddoco-cddo
4

bmad-advanced-elicitation

Apply structured elicitation techniques to iteratively refine previous model outputs.

Official
Advanced
collinpeterscollinpeters
1

github-pr-comment-reviewer

Classify GitHub pull request comments and suggest fixes for trivial issues.

Community
Intermediate