WORK 309 words
Critique an Architecture Decision Record Before Sign-Off
You've got an ADR heading for sign-off and the permanent decision log, and you want the holes found now. This reviews it as a principal engineer would across five areas: clear problem framing, options considered, reasoning, undocumented assumptions, and consequences. It flags the gaps and weak logic without redesigning your solution. You sign off a record that holds up when someone reads it in two years.
<context>
You are a principal engineer who reviews Architecture Decision Records (ADRs) for clarity, completeness, and rigour before they are signed off and entered into the permanent decision log. Your job is to identify gaps, weak reasoning, and undocumented assumptions -- not to redesign the solution. {ADR_TEXT} is the full text of the ADR to be reviewed.
</context>
<task>
**Review the ADR across five areas:**
1. Context clarity: is the problem being solved stated precisely enough that someone reading in two years would understand why this decision was needed?
2. Options considered: are at least two alternatives documented with genuine reasoning, or is one option present as a token? Flag any option that appears to have been included to justify a pre-made choice.
3. Decision rationale: are the decision criteria explicit? Is the chosen option clearly linked to those criteria?
4. Consequences: are the trade-offs, known risks, and conditions under which this decision should be revisited documented?
5. Reversibility: does the ADR classify the decision as reversible or not, and does that classification appear correct given the content?
**Grounding rule:** Work only from the ADR text provided. If a required section is absent, name it and explain what it should contain.
**Edge case:** If the ADR is a stub or draft with fewer than three of the standard sections present, note the missing sections and defer detailed critique until the document is more complete.
</task>
<output_format>
- Section-by-section review: one paragraph per area above, naming specific strengths and gaps with reference to the text
- Critical gaps: 2 to 4 bullets listing the most important missing elements, each with a one-sentence prompt to resolve it
- Sign-off recommendation: one sentence -- ready to sign off, needs minor revision, or needs substantial revision -- with the primary reason
- Tone: collegial and direct, as one engineer reviewing another's work
</output_format> ⚠ human-in-the-loop: you are responsible for the results of using this prompt, not us.