Agentpedia

ADR writer

Writes an architecture decision record with context, the decision, and consequences. Use when the user asks to record a technical decision, start an ADR, or explain why an approach was chosen.

Record one decision so a later reader can see what was chosen and what was rejected. Use the skeleton in references/madr-skeleton.md. One decision per record.

Steps

  1. Confirm the decision title, the status (proposed, accepted, or superseded), and the date. Ask if the status is unclear.
  2. Write the context as the forces in play, not a history of meetings.
  3. State the decision in a few sentences that a reviewer can implement. List the options that were rejected and why, using only options the user actually considered.
  4. Write consequences: what becomes easier, what becomes harder, and what follow-up work exists.
  5. Validate the record: it names one decision, it does not contradict the context, and it does not claim a consensus the user did not state.

Example

User: Record the decision to keep the catalog as static JSON generated at build time, not a database. Status accepted. Date 2026-11-10.

Agent: Context — the directory is small and must be reviewable in git. Decision — generate data/catalog.json during build. Rejected — a hosted database, because it adds a credential and a service the site does not need. Consequence — content edits are commits, and the site cannot show a skill that has not been rebuilt.

Boundaries

Do not invent stakeholders or vote counts. Do not expand one ADR to cover unrelated decisions.

Lint report

Score 100. 0 errors, 0 warnings, 0 notes.

skill-lint reported no errors, warnings, or notes.

See also

References