hl-adr ยท diff

git:20261013.59162d2 to git:20261013.8aa3bde

61 added, 2 removed. Audit A to A.

---
name: hl-adr
description: "Draft an architecture decision record (ADR): context, options actually considered, decision, consequences, and reversal cost. Use when a consequential technical decision needs to be recorded."
---
# ADR
Input: `[decision summary or context path]`
- Use the input as the decision or context path. Missing decision: ask for it. Several decisions: list them, draft the first, and offer one ADR for each other.
+ Use the input as the decision or context path. Missing decision: stop, as the Output section says. Several decisions: draft the first, and name each other one in the sentence under line 1 (see Output).
- First line: the suggested file name and its status, together. Then one ADR: title, status, date, context, options actually considered, decision and reason, consequences, and reversal cost. Cite current source where relevant. Use Proposed unless the input cites a recorded approval, such as a merged change or meeting notes; "we chose" alone is not one.
+ Line 1 names the file and the decision; the status goes on the verdict line, as the Output section shows. Then one ADR: title, status, date, context, options actually considered, decision and reason, consequences, and reversal cost. Cite current source where relevant. Use Proposed unless the input cites a recorded approval, such as a merged change or meeting notes; "we chose" alone is not one.
Do not invent alternatives, criteria, weights, or scores to fill a matrix. Include a comparison only when supported by the discussion.
Name the file `<NNNN>-<kebab-case-title>.md`, with the next number in the repository's ADR sequence; no numbered ADR file in the repository: the number is unknown, so write `<NNNN>` literally in the file name and the title, never `0001`. Do not write the file.
+
+ ## Output
+
+ Reader: the person who made the decision, or a reviewer. They check the draft, then save it as the record. An ADR (architecture decision record) is a short file that explains one technical choice.
+
+ Line 1, bold, one plain sentence within 100 characters: what was drafted, and the file name to save it as (`<NNNN>` when the number is unknown). Use the user's words for the decision.
+
+ Under line 1, plain sentences without labels: the decision, the reason the input gave, and the reversal cost (the work to undo the choice). When the input gives no reversal cost, say it is not stated and needs filling in. Then, only when the input holds more decisions, one sentence: `I also found: <decision>. Say "next" to draft it.`
+
+ Then the ADR in one `markdown` fence, complete, so it can be saved as is. Only the ADR goes in the fence; line 1 and the sentences around the fence are plain text. Above the fence, one plain line per `<...>` placeholder the block still holds.
+
+ End with `Verdict: <word>` on its own line, then `**Next:**`:
+ - `Proposed`: a draft the team has not agreed to.
+ - `Stopped`: no decision to record.
+
+ Stopped, no decision: line 1 says in plain words what is missing and why it blocks: `**I need the decision before I can draft the record: what was chosen, and why.**` Then `Verdict: Stopped`, then `Send one of these:` and up to 3 numbered ways, default marked: a sentence such as "we chose X over Y because Z" (default); a path to meeting notes or a pull request. Naming the options you rejected also helps; the record shows only the ones you name.
+
+ Reader rules:
+ - Write each option as one sentence: what it is and what it costs. Spell out reversal cost at first use.
+ - Name each option as the source names it. Options and reasons come only from the input; a missing one stays a placeholder.
+
+ End: `**Next:**` with these steps, in order: check the decision and its reason; save the block as the file name in the repository's ADR folder; change `Proposed` to `Accepted` once the team agrees.
+
+ ````markdown
+ **I drafted the record of the GraphQL choice. Save it as 0004-use-graphql-for-the-mobile-api.md.**
+ The team chose GraphQL for the mobile API, so the order screen makes one request instead of four.
+ The web app keeps its REST endpoints.
+ Reversal cost is medium: the mobile screens call GraphQL directly, so a move back rewrites those calls.
+
+ ```markdown
+ # 0004. Use GraphQL for the mobile API
+
+ Status: Proposed. Date: 2025-03-04.
+
+ ## Context
+ The mobile order screen calls four REST endpoints. Each returns fields the screen does not show.
+
+ ## Options considered
+ - Keep REST and add one endpoint per screen: no new tool; one endpoint to maintain per screen.
+ - GraphQL: one query for the fields the app shows; the team learns a schema language.
+
+ ## Decision
+ Use GraphQL for the mobile API. The web app keeps its REST endpoints.
+
+ ## Consequences
+ - The order screen makes one request.
+ - The mobile team writes queries and schema types.
+
+ ## Reversal cost
+ Medium. Mobile screens call GraphQL directly, so a move back rewrites those calls.
+ ```
+
+ Verdict: Proposed
+
+ **Next:**
+ 1. Check the decision and its reason. Correct any line that is wrong.
+ 2. Save the block as `0004-use-graphql-for-the-mobile-api.md` in the ADR folder.
+ 3. Change `Proposed` to `Accepted` once the team agrees.
+ ````