Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →jayrha/adr-author
Authors Architecture Decision Records (ADRs) that capture context, considered options with trade-offs, the chosen decision, and its consequences.
Passed 19 of 22 test cases with the skill, and 9 of 22 without it.
and 10 more in the full report
10 fixed9 passed either way3 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
The instructions your model reads when the skill loads.
An Architecture Decision Record (ADR) is a short, immutable document that captures one architecturally significant decision: the forces at play (context), the realistic options, the option chosen, and the consequences that follow. ADRs form an append-only log so future maintainers can reconstruct why the system looks the way it does — not just what it does.
This skill produces rigorous ADRs that distinguish facts from opinions, force an honest options comparison, and make consequences (good, bad, and neutral) explicit.
Keywords: ADR, architecture decision record, design decision, technical decision log, MADR, Nygard, trade-off analysis, options matrix, decision rationale, superseded decision, build vs buy, framework selection, database choice, API style, architecture governance.
Write an ADR when the decision is architecturally significant — it is costly to reverse,
affects multiple teams/components, or constrains future choices. Use the checklist in
references/significance-checklist.md. If none of the criteria fire, capture it as a code
comment or a ticket instead, not an ADR.
Confirm significance. Run the decision through references/significance-checklist.md.
If it does not qualify, tell the user and suggest a lighter-weight record.
Assign an ID and locate the log. ADRs live in a directory such as docs/adr/ or
doc/architecture/decisions/. Number them sequentially with a zero-padded prefix:
0001-use-postgresql.md, 0002-adopt-rest-over-graphql.md. Use
scripts/new_adr.py to scan the directory, compute the next number, and scaffold the file.
Gather context. Interview the user (or read the codebase) to extract the forces: business drivers, technical constraints, team skills, deadlines, existing systems, non-functional requirements (performance, security, cost, operability). Separate objective facts from assumptions — label assumptions explicitly.
Enumerate real options. List 2-4 genuinely viable options. "Do nothing" is often a valid option and should appear when relevant. Reject straw-man options. For each option,
test cases passed, vs 9 / 22 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.