Documentation and ADRs

Overview

An architecture decision record is a short, numbered file in the repository that captures one decision: the situation that forced it, the options that were on the table, what was chosen, and what the team now has to live with. Records are appended, never rewritten, so the log reads as the history of the design.

This skill writes those records in the two formats the field has settled on (Michael Nygard's 2011 layout and MADR 4.0), handles reversals, and brings the README, reference comments and changelog into line with the same change. It ends with a check that can fail, so the log stays trustworthy.

Instructions

1. Read the repository before writing

Look for what already exists and follow it; a log with two formats is worse than either one.

• Decision log: docs/decisions/, docs/adr/, doc/adr/, doc/architecture/decisions/, or the directory named in a .adr-dir file. Note the format, the number width and the highest number in use.
• CHANGELOG.md and its heading style, the README's sections, the comment convention in code (TSDoc, JSDoc, docstrings), an OpenAPI file.

Then ask the user only for what the code cannot show: who took the decision and when, which alternatives were seriously considered and what ruled each one out, what downside was knowingly accepted, and whether the decision is still open (proposed) or settled (accepted). Never invent a rejected option or a reason. If the answer is unknown, write "not recorded" in that place.