skills.rest
jterratsdev
jterratsdevOFFICIAL
Explore all skills by this author →
WebsiteGitHub

record-adr

Writes ADP-style Markdown ADRs and round-trips them into setup-agents decision records.

Updated Dec 1, 2025
Search Tags:#documentation#markdown#decision record#adr#jsonl#architecture decision#round-trip
One-click install
npx skills add https://github.com/jterratsdev/smart-deployment --skill record-adr-jterratsdev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: record-adr
Source: https://github.com/jterratsdev/smart-deployment/tree/main/.setup-agents/skills/record-adr
Command: npx skills add https://github.com/jterratsdev/smart-deployment --skill record-adr-jterratsdev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architecture decisions often get lost in chat threads or wikis, making them impossible to review in diffs or query programmatically. This Skill captures decisions as structured Markdown ADRs and keeps them synchronized with a JSONL decision store so both humans and workflows can consume them. ## Core Features & Use Cases - Standardized ADR Authoring: Produces ADP-style Markdown ADRs with Context, Decision, Consequences, and Alternatives sections. - Lossless Round-Trip Translation: Converts between Markdown ADRs and SetupAgentsDecisionRecord entries using adrMarkdownToRecord and recordToAdrMarkdown, carrying Consequences inside a machine-managed adr-carry block. - Decision Store Integration: Persists records via the setup-agents decision add CLI so decisions live in .setup-agents/state/decisions.jsonl. - Use Case: After choosing a data model for a new integration, draft the ADR, convert it to a decision record, and commit both so reviewers see the rationale in the diff and the workflow can query it later. ## Quick Start Ask the assistant to record an architecture decision as an ADR for the decision you just made, including its context, chosen outcome, and rejected alternatives.

Frequently Asked Questions about record-adr

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

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

Draft the ADR with four sections: Context, Decision, Consequences, and Alternatives, then convert it with adrMarkdownToRecord and persist it via the setup-agents decision add command. The title becomes the decision summary.

How do I convert a Markdown ADR to a JSON decision record?▼

Use adrMarkdownToRecord from src/services/adr-translator.ts, passing the Markdown plus owner and taskIds. The title maps to summary, Context to rationale, Decision to outcome, and Alternatives to the alternatives array.

Where are ADR decision records stored?▼

Decision records are persisted in .setup-agents/state/decisions.jsonl through the sf setup-agents decision add or orchestra decision add commands. The summary, rationale, outcome, and alternative flags map directly to record fields.

Why is the Consequences section not a separate field in the decision record?▼

The decision record schema has no dedicated Consequences field, so the translator embeds it inside rationale under an adr-carry delimiter block. This keeps both record-to-Markdown and Markdown-to-record round-trips lossless.

Can I edit the adr-carry block inside the rationale field?▼

No, the adr-carry block is machine-managed for lossless round-trip conversion and must not be hand-edited. Edit the rationale content above the delimiter block instead.

Related Skills

Explore More Software Engineering Skills→
amdmaxamdmax
2

gather-context

Gather technical context from documentation, codebase analysis, architecture files, and ADRs.

Community
Advanced
jmrplensjmrplens
37

create-architectural-decision-record

Generates structured Architectural Decision Record documents with standardized front matter and coded sections.

Community
Basic
ninthwave-ioninthwave-io
8

decision-triage

Generate ADRs, edits, or work items for each decision inbox entry.

Official
Advanced
eugenelimeugenelim
15

confluence-publisher

Publish Markdown, storage XHTML, or plain text to Confluence pages.

Community
Advanced