skills.rest
jcafeitosa
jcafeitosaCOMMUNITY
Explore all skills by this author →
Website𝕏@jcafeitosaGitHub

record-a-decision

Writes architecture decision records in Nygard/MADR format under a decisions directory.

Updated Sep 7, 2026
Search Tags:#documentation#markdown#adr#decision log#madr#architecture decision#supersedes
One-click install
npx skills add https://github.com/jcafeitosa/anxionOS --skill record-a-decision-jcafeitosa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: record-a-decision
Source: https://github.com/jcafeitosa/anxionOS/tree/main/.cursor/skills/record-a-decision
Command: npx skills add https://github.com/jcafeitosa/anxionOS --skill record-a-decision-jcafeitosa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose the reasoning behind architectural choices over time, leaving future maintainers unable to understand why a system was built a certain way. This Skill captures settled decisions as frozen, dated ADR documents with context, rejected alternatives, and honest consequences. ## Core Features & Use Cases - Structured ADR authoring: Creates numbered records (NNNN-title.md) from a template with exactly Context, Decision, and Consequences sections, plus frontmatter for status, deciders, and supersedes chains. - Supersedes chain management: Wires replacement decisions in both directions, flipping the old record to superseded status without rewriting its frozen prose. - Prior-art scanning: Searches existing decisions and proposals before writing to surface contradictions and link parent proposals. - Use Case: After a team agrees to adopt event sourcing for the orders service, use this Skill to scan prior decisions, allocate the next ADR number, record the rejected alternatives, and supersede the old REST-based decision. ## Quick Start Record the decision we just made to adopt event sourcing for orders as an ADR, superseding the old REST API decision.

Frequently Asked Questions about record-a-decision

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

FAQPage Schema
How do I write an architecture decision record (ADR)?▼

An ADR captures one settled decision with three sections: Context describing the forces at play, Decision stating what will be done in active voice, and Consequences covering both benefits and costs. Files are named NNNN-title.md with frontmatter for status, date, and deciders.

How do I supersede an old ADR with a new decision?▼

Add the old record's path to the new ADR's supersedes frontmatter, then flip the old record's status to superseded and add a forward link to the new record. Never rewrite the old record's Context, Decision, or Consequences prose, since ADRs are frozen history.

When should I write an ADR versus a proposal?▼

Write an ADR only after a decision has actually been made. If options are still being weighed or compared, frame a proposal first; the ADR records the settled outcome and links back to its parent proposal.

What is the difference between Nygard and MADR ADR formats?▼

Both formats capture context, decision, and consequences in a small dated document. This Skill uses a template with exactly those three H2 sections plus frontmatter carrying status values of proposed, accepted, deprecated, or superseded.

Why should an ADR include negative consequences?▼

A record with only upside is marketing, not a decision log. Honest costs, new obligations, and foreclosed options are what future teams check when the decision starts to hurt, so every ADR should name at least one genuine negative.

Related Skills

Explore More Software Engineering Skills→
PoyoPoakPoyoPoak

architecture

Document architecture decisions by comparing technologies and capturing trade-offs.

Community
Advanced
amoutiersamoutiers
1

x-adr

Draft architectural decision records using adr-template.md and update the ADR index.

Community
Advanced
Davie521Davie521
7

design-challenge

Generate a structured critique of a design proposal with four sections: Assumptions, Failure modes, Alternatives, Recommendation.

Community
Advanced
lookatitudelookatitude
6

guild-decisions

Capture uncertainty and decision rationale into ADR-lite wiki pages.

Community
Advanced