skills.rest
inkeep
inkeepOFFICIAL
Explore all skills by this author →
Website𝕏@inkeepGitHub

record-a-decision

Writes architecture decision records as Nygard/MADR-shaped ADRs under a decisions directory.

3.9k|256|Updated Jun 3, 2026
Search Tags:#ADR#Markdown#decision log#Documentation#architecture decision record#software-lifecycle#supersedes
One-click install
npx skills add https://github.com/inkeep/open-knowledge --skill record-a-decision
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: record-a-decision
Source: https://github.com/inkeep/open-knowledge/tree/main/packages/server/assets/skills/packs/software-lifecycle/record-a-decision
Command: npx skills add https://github.com/inkeep/open-knowledge --skill record-a-decision

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Teams lose the reasoning behind architectural choices over time, leaving future engineers unable to understand why a system was built a certain way. This Skill records settled decisions as structured, dated ADRs so the context, rejected alternatives, and consequences stay on the record permanently.

Core Features & Use Cases

  • Structured ADR authoring: Creates numbered ADR files (NNNN-title.md) from a template with exactly Context, Decision, and Consequences sections, plus frontmatter for status, date, deciders, and supersedes.
  • Supersedes chain management: Wires replacement decisions in both directions, flipping the old record to superseded and adding a forward link without rewriting frozen history.
  • Prior-art scanning and validation: Searches existing decisions and proposals before writing, then audits links and frontmatter so the decision log stays consistent.
  • Use Case: After your team agrees to adopt event sourcing for the orders service, ask the agent to record the decision; it allocates the next ADR number, documents the rejected alternatives, links the parent proposal, and supersedes the outdated REST API record.

Quick Start

Ask your AI agent to record the architecture decision we just made about adopting event sourcing for orders as an ADR in the decisions folder.

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 decision in three sections: Context (the forces that made the choice necessary), Decision (what was chosen and which alternatives lost), and Consequences (costs and benefits in both directions). This Skill creates the file from a template with numbered filenames and status frontmatter.

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

Create the new ADR with the old record's path in its supersedes frontmatter, then flip the old record's status to superseded and add a forward link to the new file. 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 you are still weighing options or asking whether to choose X or Y, frame a proposal first; the ADR records the settled outcome and links back to the proposal it graduated from.

What filename and status format do ADRs use?▼

Filenames follow NNNN-title.md with a zero-padded 4-digit sequence number and kebab-case title, starting at 0001. Status values are proposed, accepted, deprecated, or superseded, and a record stays proposed until the deciders sign off.

Does this skill work without the OpenKnowledge MCP server?▼

No. The workflow relies on OpenKnowledge MCP tools such as search, write, edit, links, and audit to scan prior decisions, create templated files, wire supersedes chains, and validate links. It is installed project-local via ok seed with the software-lifecycle pack.

Related Skills

Explore More Software Engineering Skills→
hpsgdhpsgd

council

Facilitate structured four-persona debate rounds and synthesize consensus with recommendations.

Official
Advanced
huangbaixunhuangbaixun
3

harness:writing-plans

Generate an end-to-end implementation plan from requirements with acceptance-criteria traceability and scope boundaries.

Community
Advanced
xbpk3txbpk3t

adversarial-document-reviewer

Challenge document premises and surface unstated assumptions in technical documents.

Community
Advanced
claushaasclaushaas

docs-adr

Capture architecture decisions and ADRs with context, decision, and consequences.

Community
Basic