Codex adr-writer skill for consequential architecture decisions

Record consequential trade-offs in an ADR and describe which implementation issues depend on the decision.

Install in Codex

A local Codex project with ADR naming conventions. Have the decision, alternatives, trade-offs, and traceable evidence ready.

Review `.agents/skills/adr-writer/SKILL.md` and its requirements at the pinned GitHub commit.
Create `.agents/skills/adr-writer/` in your project and save the reviewed file as `.agents/skills/adr-writer/SKILL.md`.
Start Codex from that project's root, then type `$adr-writer` and select the matching skill.

Example task

Select adr-writer in Codex. Check the ADR threshold for this fictional route data choice and draft the record.
repo ADR convention `docs/adr/` | next ID `ADR-004`
proposal=store route geometry as structured coordinates | option rejected `opaque image`
trade-off=export becomes larger; searchable coordinates enable downstream reports
reversal=would require migration after release | context=evidence from route report spec
ADR issue `ADR-004` | dependent implementation issue `IMP-014`

What to check

Explain the migration cost, necessary context, and meaningful trade-off. Keep `opaque image` as a rejected option and record `IMP-014` as blocked by `ADR-004`.

Original SKILL.md on GitHub · Updated 2026-11-14

Frequently asked question

Does an ordinary reversible change need an ADR?

Check whether it is hard to reverse, surprising without context, and a meaningful trade-off. A change below the threshold can remain in ordinary design notes.