# Obsidian Adr

> Specialist skill for Architecture Decision Records (ADRs) in an Obsidian vault. Normally invoked by the obsidian-documentation orchestrator. Use whenever a technical decision was made or is being made — "we decided to…", "we chose X over Y", "record this decision", "why did we pick…" — even if the user doesn't say "ADR". Creates numbered records under ADRs/ and manages their lifecycle (proposed, accepted, superseded).

- Skill: `rubber-ducks-syndicate/obsidian-adr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rubber-ducks-syndicate/obsidian-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rubber-ducks-syndicate/obsidian-adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: rubber-ducks-syndicate (https://skillmd.com/u/rubber-ducks-syndicate)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rubber-ducks-syndicate/obsidian-adr

---


# ADR Specialist

You record **decisions and their reasoning** so future readers understand why the system is the way it is. Output goes to `ADRs/` as `ADR-NNNN - Short Title.md`.

Read `../obsidian-documentation/references/conventions.md` first.

## When to use / not use

- **Use**: a choice between alternatives was made (library, pattern, architecture, process), or the user wants the reasoning behind an existing choice preserved
- **Don't use**: describing how something works (→ obsidian-feature / obsidian-architecture). An ADR captures the *fork in the road*, not the road.

## Rules

1. **Numbering**: scan `ADRs/` for the highest existing number and increment. Never renumber existing ADRs.
2. **Immutability**: accepted ADRs are historical records. Don't rewrite them when things change — write a new ADR that **supersedes** the old one, and update the old ADR's status to `superseded by [[ADR-NNNN - …]]`.
3. **The "why" is mandatory.** If the conversation contains the decision but not the reasoning or the alternatives considered, ask. An ADR without honest trade-offs is worthless.
4. One decision per ADR. Two decisions → two ADRs.

## ADR template

```markdown
---
created: <date>
updated: <date>
type: adr
status: proposed | accepted | superseded | rejected
tags: [adr, <domain tags>]
related: ["[[<affected notes>]]"]
---

# ADR-NNNN: <Decision in one short sentence>

## Status

<accepted (YYYY-MM-DD)> <"superseded by [[ADR-MMMM - …]]" if applicable>

## Context

<The situation that forced a choice, in plain language. What problem,
what constraints (time, money, team, tech).>

## Decision

<What was decided, stated plainly. "We will use GraphQL for all new
client-facing APIs.">

## Alternatives considered

<Each real alternative with its honest pros/cons and why it lost.>

## Consequences

<What gets better, what gets worse, what we accept. Include the costs —
every decision has them.>

## Related

- [[ADRs MOC]]
- <affected architecture/feature notes>
```

## After writing

Tell the orchestrator which existing notes are affected so obsidian-linking can connect them (the affected architecture note should link to the ADR and vice versa), and whether obsidian-architecture should update an overview to reflect the decision.

## Example

**Input**: "We're going with Postgres over DynamoDB for the orders service — the access patterns are too relational."

**Output**: `ADRs/ADR-0012 - Use Postgres for Orders Service.md` with status accepted, context (relational access patterns, team familiarity), alternatives (DynamoDB: scales better, but awkward joins and unfamiliar), consequences (must manage migrations and connection pooling; gains flexible querying). Flags `Architecture/Orders Service.md` for linking.