record-a-decision

Records an architecture decision as a Nygard/MADR-shaped ADR under decisions/ — capturing the context that forced the choice, the options weighed, the decision itself, and its consequences in both directions, plus the supersedes chain that keeps a decision log honest. Read when asked to record an architecture decision, write an ADR, log the decision we made, document why we chose X over Y, capture this decision for the record, or supersede an old decision with a new one. Do NOT read to frame a proposal or explore an idea not yet decided (frame-a-proposal), to write a spec or implementation plan (write-a-spec), to write an incident postmortem (write-a-postmortem), or to judge whether a design is sound (review-a-design). This skill records a decision already made; it does not make one.

Quality

96%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a tightly sequenced, highly actionable instruction skill with concrete tool-call signatures, hard gates, and validation feedback loops for destructive supersede edits. Its only weakness is mild repetition of a few admonitions across sections.

Suggestions

Consolidate the repeated 'ADRs are frozen / do not decide' guidance so it is stated once (e.g. in Non-goals) and referenced rather than restated in Step 0, Step 6, and Step 7.

The supersedes-chain edit templates in Step 7 could be moved to a short reference snippet to keep the main flow leaner, though this is optional given there are no bundle files today.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and dense with craft guidance Claude would not derive (ADR freezing, both-direction supersedes chain, status gating), but a few admonitions recur across Step 0, Step 7, and Non-goals ('do not decide', 'ADRs are frozen') and could be trimmed; not a 5 because of that mild repetition.	4 / 5
Actionability	Gives copy-paste-ready tool calls with real signatures (write/edit with document paths, exec commands, audit, links), the exact frontmatter scaffold, and the exact filename format — fully actionable instruction guidance covering the common cases.	5 / 5
Workflow Clarity	A clear 9-step sequence with an explicit HARD GATE up front, a prior-art scan, and validation checkpoints (audit must return clean; fix every finding before shipping), with feedback loops for the destructive supersede/status-flip edits.	5 / 5
Progressive Disclosure	No bundle files exist, so all content is inline in a single well-organized SKILL.md with clear Step 0–9 headers and a Non-goals section; per the simple/no-external-reference guideline, well-organized sections with no needed external files score 5.	5 / 5
	Total	19 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is a strong, third-person, trigger-rich statement that crisply states what the skill does, when to read it, and when not to. It covers concrete actions and disambiguates from sibling skills. No changes needed.

Dimension	Reasoning	Score
Specificity	Names the artifact (a Nygard/MADR-shaped ADR under decisions/) and lists multiple concrete actions: capturing context, options weighed, the decision, consequences 'in both directions', and the supersedes chain — comprehensive concrete coverage rather than generic verbs.	5 / 5
Completeness	Explicitly answers both 'what' (records an ADR capturing context/options/decision/consequences/supersedes) and 'when' ('Read when...') with concrete trigger phrases, and adds boundary guidance so it clearly is not the level below where 'when' is only weakly implied.	5 / 5
Trigger Term Quality	Densely packed natural trigger phrases a user would actually say ('record an architecture decision', 'write an ADR', 'log the decision we made', 'document why we chose X over Y', 'supersede an old decision'), plus explicit negative triggers for sibling skills.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (recording a settled decision) and explicitly disambiguates against frame-a-proposal, write-a-spec, write-a-postmortem, and review-a-design, giving minimal trigger-conflict risk.	5 / 5
	Total	20 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
relative_links	Relative link issues: 3 missing	Warning

	Total	14 / 16 Passed

Repository: inkeep/open-knowledge
Path: packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md
Commit: 60997a2

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.