Skip to content
Documents

Documentation and ADRs

Record an architecture decision with its constraints, rejected options and consequences, then check for drift.

Install with Skills CLI
npx skills add addyosmani/agent-skills@documentation-and-adrs

What it does

A diagram can show which database a service uses while leaving the reason for the choice unexplained. Documentation and ADRs records that reasoning and helps a maintainer revisit claims when implementation changes.

What changes after install

  • Follow the repository's existing decision-record convention.
  • Describe alternatives and the costs of the selected option.
  • Check documented claims against evidence in the current code.

Install

Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.

Install with Skills CLI
npx skills add addyosmani/agent-skills@documentation-and-adrs

Before using Documentation and ADRs

  • A repository or design record, the decision constraints, and evidence of the alternatives considered.

Read the reviewed setup instructions for the selected workflow.

When to use it

  • Capture the rationale for a consequential architecture choice.
  • Audit an existing guide against public interfaces or implementation.

When not to use it

  • Writing an authoritative decision before stakeholders have chosen an option.

A worked example

Draft a record for introducing a queue between two services. Supply the team’s design discussion, the API’s delivery requirements and the last two decisions in the repository. In this example the order service must acknowledge a request while the dispatch service is unavailable. The team considered calling dispatch synchronously. Nobody has approved the queue yet. Ask for a proposed decision that an on-call engineer could use to understand why messages may arrive late.

  1. Open the two neighboring decisions and any project instructions for ADRs. Copy their directory, numbering convention, file extension and heading names. If the last record is 0017 and the project uses reStructuredText, check that 0018 is free and continue that series. Creating a second Markdown directory would make the draft harder for the next reviewer to discover.
  2. Write the constraint from the supplied discussion in the context section. Distinguish acknowledging the order from completing dispatch. Ask which of those events the API promises its caller. A queue can let one happen before the other. If the API promises completed dispatch, the proposal changes the caller’s contract and needs that decision recorded explicitly.
  3. Describe the proposed handoff and the rejected synchronous call. Give the call its strongest case: the caller receives an immediate dispatch outcome and the operator has one request to trace. Then describe what happens to that request during a dispatch outage. Cite the design discussion for the requirement that decides between these options.
  4. Record the consequences in terms of work somebody will own. Ask who watches queue depth and who handles a message that cannot be delivered. Distinguish an agreed operating procedure from an unresolved question. Keep a proposed mitigation in the discussion if nobody has agreed to maintain it.
  5. Set the status using the evidence supplied. A merged prototype establishes that someone explored the design. It does not identify the person or meeting that approved adopting it. Leave the record proposed and give the reviewer the decision and open question to resolve.

Upstream instructions: SKILL.md.

Troubleshooting

  • The draft starts a second numbering sequence. Read the repository’s existing ADR index, configuration and most recent file together. If the configuration points to an older directory, show the maintainer the two paths and ask which one is current. Renaming every old record would break references to decisions outside this proposal.
  • The alternatives section is empty or dismisses the other design in a sentence. Recover the rejected proposal from the design discussion. Write down a circumstance in which the synchronous call would work well and the particular requirement it misses here. If the team never evaluated a suggested third option, leave it out of the decision history.
  • A code sample describes an endpoint the application no longer serves. Trace the link to its public entry point and compare the current request and response with the example. Check recent code changes for the point at which they diverged. A newer modification date on the guide alone cannot establish that someone checked this example.

How it chooses an approach

Keep local implementation detail near the code. A comment next to a retry interval can explain an unusual value. An ADR can explain why the operations team now owns retries, what alternative was rejected and what would justify revisiting that choice. A future maintainer looking to remove the queue will need that reasoning even if the queue library has changed twice since the decision.

Choose API documentation when the question is what a caller should send and expect today. For the order service, that might include the response indicating acceptance and the way to query dispatch status. Link that contract from the record if it exists. Avoid freezing a second copy of the response schema in the decision; a later field rename would give readers two competing definitions.

When a newer decision replaces this design, preserve the rationale that was true at the time. Mark the older record as superseded and identify its successor using the repository’s conventions. Someone investigating a past outage should still be able to find the design the system used then and the point at which responsibility changed hands.

When to use another skill

  • Use Writing for Agents for project rules that should shape future changes, such as where agents should look for accepted decisions before proposing another queue.
  • Use JSON Canvas to diagram the two delivery paths for a design meeting. Give it the order, acknowledgment and dispatch events so the diagram preserves the distinction that decided the proposal.
  • Use Requesting Code Review once an implementation is ready. Supply the accepted decision and the change under review so the reviewer can check whether the new behavior matches the promised API contract.

What to check after it runs

  • Open the decision from the existing index or its neighboring directory. Check the number, date and status against the other records and the approval evidence. A reader should be able to identify a proposed change without opening the implementation.
  • Ask a reviewer to point to the rejected option, name the requirement it failed and say when that option might become viable again. If the only answer is “the queue scales better,” return to the concrete outage and acknowledgment requirements.
  • Follow the links to the design discussion and the public API. Read the current response and compare its meaning with the sentence about acceptance. Flag a mismatch if the record promises completed dispatch while the API acknowledges only receipt.
  • Read the consequences from the on-call engineer’s perspective. Locate the owner of failed deliveries or the explicit question asking who that owner will be. Check that a future change of mind can be recorded through a successor link without erasing the original trade-off.

More in Documents

Related skills in other categories

FAQ

How can a team detect drift after writing an ADR?
Review specific claims against code, configuration and public behavior when the affected implementation changes. The upstream guide includes a documentation drift review.
Should a replacement decision erase the previous one?
Keep the historical rationale and record the superseding decision using the repository's existing ADR convention.