ADR Consistency Check Prompt

This prompt is designed for architects and engineering leads who maintain a repository of 10 or more Architecture Decision Records (ADRs) and need to detect silent conflicts between decisions made at different times, by different teams, or for different subsystems. The job-to-be-done is pairwise comparison of decision records to surface contradictory choices, incompatible constraints, and decisions that undermine each other. Use this prompt before architecture review boards, during dependency mapping exercises, or as a pre-merge gate when a new ADR is proposed against an existing repository. The output is a structured conflict report with severity classification, evidence from the source ADRs, and recommended resolution paths.

The ideal user has a directory of ADRs in a consistent format—typically Markdown files following a template with sections for Context, Decision, Consequences, and Constraints. The prompt expects you to provide the full text of two or more ADRs as input. It performs pairwise comparison, so for a repository of N ADRs, you should run it systematically across all pairs or use a script to batch the comparisons. Each comparison identifies conflicts such as incompatible technology choices (e.g., one ADR mandates synchronous communication while another assumes eventual consistency), contradictory constraints (e.g., one ADR requires strong consistency guarantees while another selects an eventually consistent data store), and undermining decisions (e.g., a later ADR introduces a dependency that violates the isolation boundary established by an earlier ADR). The prompt classifies each conflict by severity—Critical for decisions that cannot coexist without breaking correctness guarantees, High for decisions that create significant operational friction or rework, Medium for decisions that introduce inconsistency but can be mitigated, and Low for stylistic or minor divergence.

Do not use this prompt when you have fewer than 10 ADRs, as manual review is more efficient and the pairwise comparison overhead isn't justified. Do not use it as a substitute for human architectural judgment—the prompt identifies syntactic and structural conflicts but cannot assess whether a deliberate departure from an earlier decision is justified by changed circumstances. Do not use it on ADRs that lack consistent structure or are missing key sections like Constraints and Consequences, as the comparison logic depends on extracting comparable elements. If your ADRs are spread across multiple repositories or formats, normalize them into a consistent structure before running this prompt. For high-risk domains such as safety-critical systems, financial compliance, or healthcare, always pair automated conflict detection with human review—the prompt can miss conflicts that require domain-specific reasoning about regulations, failure modes, or operational context. After receiving the conflict report, prioritize Critical and High-severity findings for immediate discussion in an architecture review, and use Medium-severity findings as input for dependency mapping and technical debt tracking.

The template below is designed to be pasted directly into your AI harness. It accepts a list of ADRs and performs pairwise comparison to identify decisions that conflict, constrain, or undermine each other. Every variable is enclosed in square brackets—replace them with your actual ADR content, output schema, and operational constraints before execution. The prompt is structured to force structured reasoning before producing a final report, which reduces the risk of superficial or missed conflicts.

textCopy
You are an architecture reviewer analyzing a repository of Architecture Decision Records (ADRs) for consistency. Your task is to detect conflicts, contradictions, and incompatibilities between decisions.

## INPUT ADRs
[ADR_LIST]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "conflicts": [
    {
      "adr_pair": ["ADR-001", "ADR-002"],
      "severity": "critical" | "high" | "medium" | "low",
      "conflict_type": "direct_contradiction" | "incompatible_constraint" | "undermining_decision" | "timing_conflict" | "resource_conflict",
      "description": "Specific description of what conflicts and why",
      "adr_excerpts": [
        {"adr_id": "ADR-001", "relevant_text": "..."},
        {"adr_id": "ADR-002", "relevant_text": "..."}
      ],
      "impact": "What breaks, is blocked, or becomes inconsistent if both ADRs stand",
      "resolution_options": ["Option 1", "Option 2"]
    }
  ],
  "consistent_pairs_checked": 0,
  "total_adrs_analyzed": 0,
  "analysis_notes": "Any patterns observed across the repository"
}

## CONSTRAINTS
[CONSTRAINTS]

## ANALYSIS RULES
1. Compare every ADR against every other ADR in the list.
2. For each pair, check for:
   - Direct contradictions (ADR-A says X, ADR-B says not-X)
   - Incompatible constraints (ADR-A requires Y, ADR-B forbids Y)
   - Undermining decisions (ADR-B makes ADR-A's rationale invalid or obsolete)
   - Timing or sequencing conflicts (ADR-A assumes Z exists, ADR-B deprecates Z)
   - Resource or ownership conflicts (both ADRs claim the same team, budget, or system)
3. Classify severity:
   - critical: System cannot function or build if both decisions stand
   - high: Major rework required; one decision must be substantially revised
   - medium: Tension exists but workarounds are possible
   - low: Minor inconsistency; documentation or clarification likely sufficient
4. Only report actual conflicts. Do not flag differences in scope or context that are compatible.
5. If no conflicts exist, return an empty conflicts array with accurate counts.

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, start by replacing [ADR_LIST] with your actual ADR documents, each prefixed with its identifier. The [CONSTRAINTS] placeholder should include any domain-specific rules, such as regulatory requirements or organizational policies that ADRs must satisfy. Use [EXAMPLES] to provide one or two annotated conflict examples that demonstrate your expected severity calibration—this is especially important if your team has specific definitions for what constitutes a critical versus medium conflict. Set [RISK_LEVEL] to guide the model's caution: for production systems, use high to require explicit evidence for every flagged conflict; for exploratory analysis, medium may be acceptable. After generating the report, always validate the output against your schema before surfacing it to architects. For high-risk systems, route critical and high-severity conflicts to a human reviewer before accepting the analysis.

The ADR Consistency Check prompt is designed to operate as a batch analysis step within a documentation pipeline, not as a real-time interactive assistant. The typical integration point is a CI/CD check that runs when new ADRs are proposed or existing ADRs are modified. The harness should collect all active ADRs from the repository, format them into the [ADR_LIST] placeholder, and invoke the model. The output is a structured conflict report that downstream systems can parse and act on. Because this prompt performs pairwise comparison across all ADRs, the token budget grows quadratically with the number of documents. For repositories with more than 30-40 ADRs, implement a pre-filtering step that selects only ADRs in related domains or with overlapping architectural concerns before invoking the full consistency check.

The implementation harness requires several validation layers before the model output can be trusted. First, validate the JSON schema of the response against the expected [OUTPUT_SCHEMA]—reject any response where conflicts is not an array or where severity values fall outside the allowed enum. Second, verify that each reported conflict includes valid ADR identifiers that exist in the input list; flag any hallucinated ADR references for human review. Third, implement a retry loop with exponential backoff (max 3 attempts) for schema validation failures, using a repair prompt that includes the validation error message and the original ADR list. For high-risk architectural decisions where a false conflict or missed conflict could cause significant rework, route all critical severity findings to a human architect for confirmation before blocking a merge. Log every invocation with the model version, input ADR count, conflict count by severity, and validation pass/fail status for observability.

Model choice matters for this workflow. Use a model with strong reasoning capabilities and a large context window—GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are appropriate starting points. Avoid smaller or faster models for the initial consistency check because pairwise comparison across architectural documents requires careful logical reasoning that weaker models often fumble, producing false conflicts or missing genuine contradictions. If cost or latency is a concern, implement a two-stage pipeline: use a smaller model to identify candidate ADR pairs with potential overlap, then run the full consistency check prompt only on those pairs with a stronger model. Do not use this prompt as a real-time gate in a chat interface; the analysis is too complex and the stakes too high for synchronous human-AI interaction without review. The output conflict report should be stored alongside the ADRs in version control, creating an audit trail of when conflicts were detected, reviewed, and resolved.