skills.rest
serpro-workshop-fortaleza
serpro-workshop-fortalezaOFFICIAL
Explore all skills by this author →
GitHub

adr-draft

Draft Architecture Decision Records documenting context, alternatives, and consequences.

Updated Sep 10, 2026
Search Tags:#documentation#markdown#technical writing#adr#trade-offs#architecture decision
One-click install
npx skills add https://github.com/serpro-workshop-fortaleza/datacorp-sifap-modernization-team-kit --skill adr-draft-serpro-workshop-fortaleza
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-draft
Source: https://github.com/serpro-workshop-fortaleza/datacorp-sifap-modernization-team-kit/tree/main/.github/skills/adr-draft
Command: npx skills add https://github.com/serpro-workshop-fortaleza/datacorp-sifap-modernization-team-kit --skill adr-draft-serpro-workshop-fortaleza

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often make important architecture decisions without documenting the reasoning, alternatives, and trade-offs, making it hard to understand or revisit those choices months later. This Skill guides the creation of well-structured Architecture Decision Records (ADRs) that capture the full decision context. ## Core Features & Use Cases - ADR Drafting Guidance: Provides criteria for when a decision warrants an ADR (hard to reverse, affects multiple teams, constrains future choices) and when it does not. - Canonical Output Template: Produces ADRs saved as docs/adr/NNNN-<slug>.md with sections for Context, Decision, Alternatives Considered, Consequences, Follow-ups, and References. - Quality Checklist: Enforces standards such as at least two rejected alternatives with trade-offs, a defined status, and links to affected requirement IDs. - Use Case: When your team chooses PostgreSQL over MongoDB, use this Skill to draft ADR-0012 documenting the deciding factors, rejected options, and known negative consequences. ## Quick Start Draft an ADR for our decision to adopt an event-driven architecture and save it under docs/adr.

Frequently Asked Questions about adr-draft

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

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

Write an ADR with sections for Context, Decision, Alternatives Considered, and Consequences, saved as docs/adr/NNNN-slug.md. Include at least two rejected alternatives with their trade-offs and set a status of proposed, accepted, superseded, or deprecated.

When should I write an ADR for a technical decision?▼

Write an ADR when a decision is hard or expensive to reverse, affects more than one team, constrains future technology choices, or will likely be questioned in six months. Skip ADRs for local refactors or reversible configuration changes.

What are common ADR antipatterns to avoid?▼

Common antipatterns include writing ADRs after the fact to justify decisions already made, bundling five unrelated decisions into one record, omitting the alternatives section, and leaving the status as proposed for months.

Should old ADRs be deleted when a decision changes?▼

No, supersede rather than delete. Mark the old ADR as superseded by the new ADR number, because the historical record of past decisions and their reasoning adds long-term value to the project.

What file naming convention do ADRs follow?▼

ADRs are saved as docs/adr/NNNN-slug.md, where NNNN is a sequential number and slug is a short hyphenated title. The repository canonical template lives at docs/adr/0000-template.md.

Related Skills

Explore More Software Engineering Skills→
v4lheruv4lheru

pact-prepare-research

Standardize technology research preparation for architectural decisions.

Community
Intermediate
jacob-balslevjacob-balslev
1

architecture-decision-records

Capture and audit architecture decisions as Markdown Architecture Decision Records.

Community
Intermediate
Negentropy-LabyNegentropy-Laby
3

architecture-decision

Document architectural decisions with context, constraints, and trade-offs.

Official
Advanced
HeyItsGilbertHeyItsGilbert
1

rfc

Draft and manage structured RFCs with lifecycle states and ADR cross-linking.

Community
Advanced