skills.rest
TierOne-Studio
TierOne-StudioOFFICIAL
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

Create and maintain Architecture Decision Records for load-bearing engineering decisions.

1|Updated Apr 3, 2026
Search Tags:#documentation#technical writing#adr#architecture decisions#decision records#engineering conventions
One-click install
npx skills add https://github.com/TierOne-Studio/spa-velocity --skill documentation-and-adrs-tierone-studio
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/TierOne-Studio/spa-velocity/tree/main/.ruler/skills/documentation-and-adrs
Command: npx skills add https://github.com/TierOne-Studio/spa-velocity --skill documentation-and-adrs-tierone-studio

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering teams lose the reasoning behind structural decisions over time, leading to repeated debates and conventions whose rationale no one remembers. This Skill enforces a disciplined ADR workflow so durable decisions are recorded once, cited everywhere, and never restated inline. ## Core Features & Use Cases - ADR authoring workflow: Copy the template, number sequentially, fill Context/Decision/Alternatives/Consequences, and index the record in docs/decisions/README.md. - Superseding decisions: Mark old ADRs as superseded without rewriting them, keeping an append-only decision history. - Citation discipline: Skills and CLAUDE.md cite ADR numbers instead of restating rationale, with a layered-router rule that keeps CLAUDE.md free of artifact references. - Use Case: When introducing a new state-management library, use this Skill to write ADR-NNN capturing the rejected alternatives, then update the repo-conventions citation table to point at it. ## Quick Start Ask the assistant to propose a new ADR for the structural decision you are making, for example: draft an ADR documenting why the project uses localStorage-based auth tokens instead of session cookies.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an Architecture Decision Record?▼

Copy the ADR template from docs/decisions/_template.md, assign the next sequential number, and fill in Status, Date, Context, Decision, Alternatives considered, Consequences, and References. Then add a row to the index in docs/decisions/README.md and commit with a docs(adr) message.

When should a decision get an ADR versus a commit message?▼

A decision needs an ADR only when it constrains future code or is cited repeatedly across skills and conventions. Routine implementation, style choices, one-off fixes, and easily reversed local choices belong in commit messages or config files, not ADRs.

How do I supersede an existing ADR?▼

Update the old ADR's Status line to 'Superseded by ADR-XXX' without rewriting its body, since ADRs are append-only. Write the new ADR with a Supersedes reference, explain what changed, and update all citation sites to point at the new record.

Should CLAUDE.md reference ADR numbers directly?▼

No. CLAUDE.md acts as a pure routing layer and must not reference ADR numbers, file paths, or code symbols. ADR citations live in skills like repo-conventions and in the docs/decisions index, keeping the always-loaded router stable as artifacts grow.

What are common ADR anti-patterns to avoid?▼

Avoid editing accepted ADRs beyond status updates, writing ADRs for ephemeral decisions like indentation, listing only one alternative, and writing decisions without context. Also avoid restating ADR rationale inline in skills; cite the ADR number instead.

Related Skills

Explore More Software Engineering Skills→
brandonarbinibrandonarbini

decision-comments

Writes code comments, READMEs, and commit messages that record decisions and rationale.

Community
Basic
zgagnonzgagnon
1

adr-review

Review code against project ADRs and report violations with fixes.

Community
Advanced
MinhThang1009MinhThang1009
15

revise-claude-md

Update CLAUDE.md with session learnings following team conventions.

Community
Intermediate
robpitcherrobpitcher

history-hygiene

Record confirmed final outcomes to history.md after explicit confirmation.

Community
Intermediate