ADR Validation Checklist Prompt

Engineering teams that maintain an Architecture Decision Record (ADR) repository need consistent quality before a decision is accepted. Manual review catches some issues but is slow, inconsistent, and hard to enforce at scale. This prompt produces a structured, pass/fail validation checklist with specific criteria for each ADR section, rationale depth, and traceability. It is designed to run as a CI/CD gate on pull requests that add or modify ADRs, giving authors immediate, actionable feedback and giving reviewers a pre-validated document.

Use this prompt when you have a draft ADR and need an automated quality assessment before human approval. The ideal user is an engineering lead, architect, or platform engineer who owns the ADR quality bar and wants to shift validation left into the PR workflow. The prompt requires a complete ADR text as input—it evaluates what exists rather than generating missing sections. It works best with ADRs that follow a standard template (Title, Status, Context, Decision, Options Considered, Consequences) so the validation criteria can map to known sections. The output is a structured checklist with pass/fail status per criterion, specific citations to the ADR text that triggered failures, and an overall compliance score that can be used as a merge gate threshold.

Do not use this prompt for generating ADRs from scratch, for comparing architectural options, or for extracting context from meeting notes. It is not a drafting assistant—it assumes the ADR text is complete enough to evaluate and will not fill in missing sections. Avoid using it on ADRs that intentionally deviate from your standard template, as the validation criteria will produce false negatives. For teams just starting their ADR practice, pair this prompt with the ADR Generation Prompt Template to produce a compliant first draft, then run validation as a quality check before the review cycle begins.

This prompt template is the core of the ADR validation workflow. It takes a complete ADR document and a set of quality criteria, then produces a structured checklist with pass/fail status, specific evidence from the ADR text, and actionable remediation guidance for each failing criterion. The prompt is designed to be strict and evidence-based—it should not pass a criterion unless the ADR explicitly contains the required content.

textCopy
You are an ADR quality reviewer. Your task is to validate an architecture decision record against a defined quality standard and produce a structured pass/fail checklist.

## INPUT

### ADR Document
[ADR_CONTENT]

### Quality Criteria
[QUALITY_CRITERIA]

### Output Schema
Return a JSON object with this exact structure:
{
  "adr_title": "string",
  "overall_score": number (0-100),
  "overall_pass": boolean,
  "criteria": [
    {
      "criterion_id": "string",
      "criterion_name": "string",
      "status": "pass" | "fail" | "not_applicable",
      "evidence": "string (quote from ADR or explain absence)",
      "remediation": "string (specific fix if failed, else empty)"
    }
  ],
  "summary": "string (2-3 sentence overall assessment)"
}

## CONSTRAINTS
[CONSTRAINTS]

## INSTRUCTIONS
1. Read the entire ADR document carefully.
2. For each quality criterion, determine if the ADR satisfies it.
3. A criterion passes ONLY if the ADR contains explicit, specific content that addresses it. Do not infer, assume, or fill gaps.
4. For each failing criterion, quote the specific section or absence that caused the failure.
5. For each failing criterion, provide a concrete, actionable remediation that tells the author exactly what to add or fix.
6. Calculate overall_score as the percentage of applicable criteria that pass.
7. Set overall_pass to true only if overall_score meets the minimum threshold specified in constraints.
8. If a criterion is genuinely not applicable to this ADR type, mark it as not_applicable and explain why briefly.

To adapt this template for your team, replace the square-bracket placeholders with your actual content. [ADR_CONTENT] should contain the full ADR text, including all sections like context, decision, options considered, consequences, and metadata. [QUALITY_CRITERIA] should be a list of specific, testable criteria—for example, "ADR includes at least two alternative options with trade-offs" or "Decision rationale references specific constraints from the context section." [CONSTRAINTS] should define the minimum pass threshold, any domain-specific requirements, and whether certain sections are mandatory. After running the prompt, always validate the output JSON against the schema before accepting results. For high-stakes ADRs, route failing checklists to a human reviewer rather than auto-blocking a merge.

The ADR Validation Checklist Prompt is designed to be a deterministic quality gate, not an advisory chatbot. To use it in production, wrap the prompt in a thin application harness that controls the input assembly, model call, output parsing, and post-validation logic. The harness should treat the model's output as a structured compliance report—never as a final authority without programmatic checks. The core integration points are: a pre-commit or PR-check hook that triggers validation when ADR files change, a model invocation layer that injects the ADR content and the checklist criteria, and a post-processing step that parses the pass/fail result and attaches it as a review comment or CI status check.

Start by defining the trigger. In a GitHub Actions or GitLab CI pipeline, configure the workflow to run on pull requests that modify files in your ADR directory (e.g., docs/adr/**). The harness should extract the changed ADR file content, inject it into the [ADR_CONTENT] placeholder, and supply the [CHECKLIST_CRITERIA] from a version-controlled criteria file in the repository. This keeps the quality standard auditable and updatable without changing the prompt. For the model call, prefer a model with strong structured-output capabilities and low latency—GPT-4o or Claude 3.5 Sonnet are good defaults. Set temperature=0 and request a JSON output mode to enforce the checklist schema. Implement a retry wrapper with up to 2 retries on parse failures, using the validation error message as context for the retry. If the output still fails to parse after retries, fail the check open with a warning rather than blocking the pipeline silently.

Post-processing is where the harness earns its keep. Parse the model's JSON output and validate it against an expected schema: a top-level pass boolean, a score integer, and a checks array where each item has an id, criterion, status (pass/fail/warn), and detail string. If the pass field is false, the harness should post a structured comment on the PR with the failing checks and their details. For teams using GitHub Checks API or GitLab Merge Request notes, map the checklist results to annotations on the specific ADR file. Store the full validation result as a CI artifact for auditability. For high-risk architectural decisions (e.g., security boundaries, data storage choices, compliance-affecting changes), add a human approval gate: if the automated check fails or scores below a configurable threshold, require a designated architect's review before merge. This prevents the automation from becoming a rubber stamp while still catching the majority of incomplete or weak ADRs before human reviewers spend time on them.

Avoid wiring this prompt into a blocking gate without an override path. ADR quality is a practice, not a binary property, and edge cases exist—emergency decisions, intentionally lightweight records, or decisions where full trade-off analysis is deferred. The harness should support a skip-validation label on the PR or an adr-validation: bypass footer in the commit message that allows authorized users to override the gate while logging the bypass event. Monitor the bypass rate and the pass/fail distribution over time. If the bypass rate climbs above 10%, the criteria are probably too strict or the prompt is flagging false positives. If the pass rate is near 100%, the criteria are probably too lenient to catch real quality gaps. Treat the harness as a feedback loop: the prompt, the criteria, and the thresholds should all be tuned based on what the team actually accepts or rejects in review.