ADR Review Prompt for Architecture Decisions

Use this prompt when you are a peer reviewer, tech lead, or architect who needs to provide consistent, structured, and actionable feedback on a draft Architecture Decision Record (ADR) before it is accepted. The primary job-to-be-done is to elevate the quality of architectural decisions by catching clarity issues, unstated assumptions, missing alternatives, and weak rationale that would otherwise go unnoticed in an ad-hoc review. The prompt assumes the draft ADR is complete enough to evaluate but has not yet been merged or approved. It is designed for teams that maintain an ADR repository and want to enforce a baseline quality standard across all decisions, not just the most controversial ones.

The ideal user is someone who understands the system's architecture but wants a disciplined review framework to avoid personal bias and inconsistency. Instead of writing freeform comments like 'this needs more detail,' the prompt produces a structured review that identifies specific gaps: options that should have been considered but were not, trade-offs that are mentioned but not analyzed, and rationale that describes what was chosen without explaining why alternatives were rejected. This is particularly valuable when reviewing ADRs from less experienced architects, when onboarding new team members to the ADR process, or when preparing for a group decision meeting where multiple reviewers need to align on feedback before the discussion.

Do not use this prompt as a replacement for domain expertise, stakeholder alignment conversations, or implementation feasibility checks. The model can identify structural gaps and reasoning flaws, but it cannot validate whether the technical constraints are correct, whether the cost estimates are realistic, or whether the chosen option aligns with organizational strategy. This prompt is also not suitable for generating an ADR from scratch—use the ADR Generation Prompt Template for that. Avoid using it on decisions that are already accepted and implemented unless you are conducting a retrospective quality audit. For high-risk decisions in regulated environments, always pair the model's review with human expert validation and consider using the ADR Compliance Mapping Prompt to ensure regulatory obligations are met.

The following prompt template is designed to be dropped into your AI-assisted review workflow. It forces the model into a reviewer stance, not an authoring one, and constrains its output to a structured, actionable format. This prevents the common failure mode where the model simply rewrites the ADR instead of critiquing it. Replace the square-bracket placeholders with your specific ADR content and review parameters before execution.

codeCopy
You are an experienced software architect acting as a peer reviewer for a draft Architecture Decision Record (ADR). Your goal is to produce a structured, actionable review that identifies weaknesses, gaps, and risks before the ADR is approved. Do not rewrite the ADR. Do not suggest alternatives unless the current decision is fundamentally unsound.

## ADR TO REVIEW

**Title:** [ADR_TITLE]
**Context:** [ADR_CONTEXT]
**Decision:** [ADR_DECISION]
**Options Considered:** [ADR_OPTIONS]
**Rationale:** [ADR_RATIONALE]
**Consequences:** [ADR_CONSEQUENCES]

## REVIEW PARAMETERS

**Review Focus Areas:** [REVIEW_FOCUS_AREAS]
**Risk Tolerance:** [RISK_TOLERANCE]
**Team Context:** [TEAM_CONTEXT]

## OUTPUT SCHEMA

Produce a JSON object with the following structure:
{
  "overall_assessment": "PASS" | "NEEDS_REVISION" | "REJECT",
  "summary": "A 2-3 sentence summary of the review's key findings.",
  "findings": [
    {
      "severity": "BLOCKER" | "MAJOR" | "MINOR" | "SUGGESTION",
      "category": "CLARITY" | "COMPLETENESS" | "RATIONALE" | "ASSUMPTION" | "OPTION" | "CONSEQUENCE" | "CONTEXT",
      "location": "The specific section or statement in the ADR that triggered this finding.",
      "observation": "What the issue is, stated neutrally.",
      "recommendation": "A concrete, actionable suggestion for the author."
    }
  ],
  "missing_options": [
    "An alternative option that was not considered but should be, with a brief explanation of why it's relevant."
  ],
  "unstated_assumptions": [
    "An assumption the decision appears to depend on that is not explicitly documented."
  ],
  "risk_register": [
    {
      "risk": "A risk introduced or amplified by this decision.",
      "likelihood": "LOW" | "MEDIUM" | "HIGH",
      "impact": "LOW" | "MEDIUM" | "HIGH",
      "mitigation": "A suggested mitigation or acceptance rationale."
    }
  ]
}

## CONSTRAINTS
- Only report findings that are genuinely actionable. Do not invent issues.
- If the ADR is clear and complete, return an empty findings array and a PASS assessment.
- Do not critique writing style or grammar unless it creates genuine ambiguity about the decision.
- For each finding, you must be able to point to a specific location in the ADR.

To adapt this template, replace the [ADR_*] placeholders with the actual content from your draft ADR. The [REVIEW_FOCUS_AREAS] parameter lets you direct the review toward specific concerns like security, cost, or operational burden. Set [RISK_TOLERANCE] to LOW, MEDIUM, or HIGH to calibrate the reviewer's sensitivity. The [TEAM_CONTEXT] field should describe your team's size, expertise, and existing tech stack so the reviewer can flag decisions that are misaligned with your operational reality. Run this prompt through your model, validate the JSON output against the schema, and feed any BLOCKER or MAJOR findings back to the ADR author before the decision proceeds to approval.

The ADR review prompt is designed to operate as a pre-merge quality gate in an architecture decision repository. Wire it into your existing pull request workflow (GitHub Actions, GitLab CI, or a custom review bot) so that every new or modified ADR document triggers an automated review before human architects spend time on it. The prompt expects a complete ADR draft as input, typically a Markdown file following a template like MADR or a custom org standard. Pass the raw file content into the [ADR_DRAFT] placeholder, along with any [ORG_STANDARDS] that define required sections, naming conventions, or mandatory constraint categories. The model should return structured JSON with review findings, which your harness then parses and acts on.

Validation and retry logic is critical here because the output must be machine-readable for downstream automation. Implement a JSON schema validator that checks for required fields (clarity_issues, missing_options, unstated_assumptions, weak_rationale, overall_score, recommendation). If validation fails, retry up to two times with the error message appended to the prompt as a [PREVIOUS_ERROR] context. After two failed retries, surface the raw output to a human reviewer with a warning flag. For high-risk domains (security architecture, compliance-mapped decisions, data residency), always require human approval regardless of the automated score. The recommendation field should map to three actions: approve (auto-merge allowed if score exceeds threshold), revise (block merge, post inline comments on the PR), or escalate (flag for architecture review board).

Model choice and latency matter for developer experience. Use a fast, capable model (Claude 3.5 Sonnet or GPT-4o) for the primary review pass. If your ADR repository is large, consider a RAG step that retrieves related ADRs before calling the review prompt, populating a [RELATED_DECISIONS] context to enable consistency and dependency checks. Log every review result—including the prompt version, model, timestamp, score, and human override if applied—to build an audit trail for governance reviews. Avoid running this prompt on every commit during draft editing; trigger it only on PR creation, PR update, or a manual /review command to keep feedback loops tight and costs predictable.