dsh-skills/skills/documentation-and-adrs/SKILL.md

name, description

name	description
documentation-and-adrs	Use when documenting architectural decisions, drafting ADRs (Architecture Decision Records), or writing technical specifications and system documentation.

Architecture Decision Records (ADRs) & Technical Documentation

Purpose

Produce concise, actionable, and structured architectural documentation and ADRs that capture the context, options considered, and tradeoffs made.

ADR Standard Structure (MADR Format)

# [Short title of solved problem and decision]

* **Status:** proposed | accepted | rejected | deprecated | superseded
* **Deciders:** [List of stakeholders/engineers]
* **Date:** YYYY-MM-DD

## Context and Problem Statement
What problem are we solving? What are the constraints, requirements, and background context?

## Decision Drivers
* Driver 1 (e.g. performance under 50ms latency)
* Driver 2 (e.g. zero external infrastructure dependencies)
* Driver 3 (e.g. strict backwards compatibility)

## Considered Options
1. Option A — [Short description]
2. Option B — [Short description]
3. Option C — [Short description]

## Decision Outcome
Chosen option: "Option A", because [justification linking to drivers].

### Positive Consequences
* Clear benefit 1
* Clear benefit 2

### Negative Consequences / Tradeoffs
* Accepted limitation 1
* Migration cost or operational overhead

## Pros and Cons of Options
[Brief comparison table or bullet breakdown]

Documentation Principles

1. One Home per Fact: Do not duplicate invariants across multiple files.
2. Focus on "Why" and "Tradeoffs": Code shows how; documentation must explain why this choice was made over alternatives.
3. No Fluff / Slop: Direct, concise language. Omit generic platitudes.