skills.rest
petemcw
petemcwCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

architecture-decision-records

Capture architectural decisions as structured ADR documents with context, alternatives, and rationale.

Updated Sep 13, 2026
Search Tags:#documentation#markdown#adr#technical design#architecture decisions#decision records#codebase knowledge
One-click install
npx skills add https://github.com/petemcw/farseer --skill architecture-decision-records-petemcw
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/petemcw/farseer/tree/main/skills/architecture-decision-records
Command: npx skills add https://github.com/petemcw/farseer --skill architecture-decision-records-petemcw

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architectural decisions made during coding sessions often live only in chat threads, PR comments, or someone's memory, leaving future developers wondering why the codebase is shaped the way it is. This Skill records those decisions as structured ADR documents stored alongside the code. ## Core Features & Use Cases - Decision Detection: Recognizes explicit signals ("let's go with X") and implicit signals (framework comparisons, pattern trade-offs) that indicate a recordable architectural decision. - Structured ADR Writing: Produces lightweight Nygard-style ADRs covering context, decision, alternatives considered, and consequences, saved to .farseer/adr/ with sequential numbering. - ADR Index and Lookup: Maintains a README index of all ADRs and answers "why did we choose X?" questions by reading existing records. - Use Case: While debating PostgreSQL versus MongoDB for a new service, you settle on PostgreSQL for relational integrity. The Skill drafts ADR-0002 documenting the rejected alternative and trade-offs, then updates the index after your approval. ## Quick Start Ask the assistant to record the database choice we just discussed as an architecture decision record.

Frequently Asked Questions about architecture-decision-records

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

FAQPage Schema
How do I create an architecture decision record?▼

State the decision in conversation, such as "we decided to use PostgreSQL over MongoDB," and the Skill drafts an ADR with context, alternatives, and consequences. After your explicit approval, it writes the file to .farseer/adr/ with a sequential number and updates the index.

What format does an ADR use?▼

The Skill uses the lightweight Nygard ADR format with sections for Date, Status, Deciders, Context, Decision, Alternatives Considered, and Consequences. Each ADR is a short markdown file readable in about two minutes.

When should a decision be recorded as an ADR?▼

Record a decision when it is hard to reverse, surprising without context, and the result of a genuine trade-off between alternatives. Trivial or easily reversed choices like variable naming should be skipped.

Can I look up why a past decision was made?▼

Yes. Ask "why did we choose X?" and the Skill scans the .farseer/adr/README.md index, reads matching ADR files, and presents the Context and Decision sections. If no ADR exists, it offers to record one.

Does the Skill write ADR files automatically?▼

No. It requires explicit user confirmation before creating the .farseer/adr/ directory and before writing any ADR file. Declined drafts are discarded without writing anything.

What happens when an ADR is no longer valid?▼

ADRs follow a lifecycle of proposed, accepted, then deprecated or superseded. A superseded ADR must link to the ADR that replaces it so the decision history remains traceable.

Related Skills

Explore More Software Engineering Skills→
rchanda1392rchanda1392

brainstorm

Facilitate collaborative brainstorming and document architecture decisions in ARCHITECTURE.md.

Community
Advanced
ForgePlanForgePlan
3

decision

Capture routine decisions as structured light ADRs during code reviews.

Official
Basic
tech-leads-clubtech-leads-club
5.1k

the-fool

Challenges plans and decisions through structured devil's advocate, pre-mortem, and red team analysis.

Official
Advanced
GiantCroissant-LunarGiantCroissant-Lunar

spec-first

Locate, read, and summarize RFCs and ADRs before coding.

Official
Basic