From economist-agents
Rules for writing, numbering, and superseding Architectural Decision Records. Use when creating a new ADR, when changing an ADR's status, when consolidating or auditing the ADR tree.
npx claudepluginhub oviney/economist-agentsThis skill uses the workspace's default tool permissions.
Keeps the Architectural Decision Record tree coherent, auditable, and immutable. Every significant architectural decision lives in `docs/adr/` with consistent format, deterministic numbering, and formal supersession lifecycle.
Applies Acme Corporation brand guidelines including colors, fonts, layouts, and messaging to generated PowerPoint, Excel, and PDF documents.
Guides strict Test-Driven Development (TDD): write failing tests first for features, bugfixes, refactors before any production code. Enforces red-green-refactor cycle.
Share bugs, ideas, or general feedback.
Keeps the Architectural Decision Record tree coherent, auditable, and immutable. Every significant architectural decision lives in docs/adr/ with consistent format, deterministic numbering, and formal supersession lifecycle.
docs/adr/docs/ARCHITECTURE_PATTERNS.md or a skillRule 1: One Canonical Location. All ADRs live in docs/adr/. No files in docs/ADR-*.md or docs/architecture/ADR*.md. CI lint enforces this.
Rule 2: MADR Filename Format. Pattern: NNNN-kebab-case-title.md. Zero-padded 4-digit number, globally sequential. Numbers never reused.
Rule 3: Mandatory Header.
# ADR-NNNN: Title
**Status:** Proposed | Accepted | Rejected | Deprecated | Superseded
**Date:** YYYY-MM-DD
**Decision Maker:** <name or role>
**Supersedes:** <ADR-NNNN link, if applicable>
**Superseded by:** <ADR-NNNN link, if applicable>
Status values are a closed set — no "Implemented", "Approved", "In Progress".
Rule 4: Mandatory Body Sections. Context, Decision, Alternatives Considered, Consequences. Additional sections welcome.
Rule 5: Immutability After Accepted. Body is immutable once Accepted. Typo fixes allowed; decision content cannot be rewritten. If context changes, write a new ADR that supersedes.
Rule 6: Bidirectional Supersession. New ADR gets Supersedes: link. Old ADR status changes to Superseded with back-link. CI lint verifies both sides.
Rule 7: Not Everything Is an ADR. Only for decisions expensive to reverse: framework choice, data model, security model, agent delegation, API contracts. Ask: "If reversed in 6 months, would it cost more than a day?"
Rule 8: Index in mkdocs.yml. Every ADR must be in the nav section. Orphaned ADRs fail CI lint.
| Action | Who |
|---|---|
| Draft new ADR | Any agent |
| Propose (status: Proposed) | Any agent |
| Accept / Reject / Supersede / Deprecate | Engineering Lead only — human approval required |
scripts/lint_adrs.py — CI lint enforcing all rules (pre-commit + CI)docs/adr/TEMPLATE.md| Rationalization | Reality |
|---|---|
| "This decision isn't important enough for an ADR" | If reversing it costs more than a day, it needs one — that's the threshold |
| "I'll just update the existing ADR instead of writing a new one" | Rewriting history defeats the purpose; git blame should show original rationale |
| "We can delete rejected ADRs to keep things clean" | Future teams re-litigate the same debates without knowing why options were rejected |
| "The ADR can live next to the code it describes" | Multiple locations cause drift and collisions — one canonical directory prevents this |
| "We don't need the lint — we'll be careful" | Sprint 21 found 11+ files across 3 directories with colliding numbers; careful doesn't scale |
docs/adr/ (legacy location drift)mkdocs.yml nav sectiondocs/adr/ — evidence: scripts/lint_adrs.py passes, no files in legacy locationsNNNN-kebab-case-title.md — evidence: lint check## Context, ## Decision, ## Alternatives, ## Consequencesmkdocs.yml — evidence: lint check for orphaned ADRsscripts/lint_adrs.py passes in CI — evidence: green CI check