ADR Anti-Pattern Detection Prompt

This prompt is designed for architects, technical leads, and review board members who need to systematically audit an Architecture Decision Record (ADR) for structural weaknesses before approval. The primary job-to-be-done is quality assurance: catching logical fallacies, documentation anti-patterns, and missing rigor that would otherwise undermine the decision's traceability and defensibility. Use it as a gate before an ADR is merged into the repository, during a formal architecture review board session, or when performing a retrospective audit of an existing decision log. The ideal user has enough architectural context to judge the prompt's findings but wants an automated first pass to surface issues that are easy to miss during manual review, such as unstated assumptions masquerading as facts or options that were never genuinely considered.

The prompt assumes the input is a complete or near-complete ADR draft containing the standard sections: context, decision, options considered, trade-offs, and consequences. It is not designed for raw meeting notes, whiteboard sketches, or partial outlines. If the input lacks a clear decision statement or option enumeration, the prompt will correctly flag those as structural gaps rather than attempting to fill them in. The detection library covers high-frequency failure modes including decision-by-default (presenting only one option as inevitable), rationalization-after-the-fact (justifying a pre-made choice rather than evaluating alternatives), missing trade-offs (listing options without comparing them on cost, risk, or feasibility dimensions), option anchoring (framing all alternatives against a favored choice), and unstated assumptions (treating team capability, budget, or timeline constraints as implicit rather than documented). Each flagged issue includes a severity rating and specific remediation guidance tied to the ADR text.

Do not use this prompt for generating new ADRs, for general code review, or for evaluating the technical correctness of the decision itself. It detects documentation and reasoning quality issues, not whether the chosen architecture will work. The prompt is also not a substitute for human architectural judgment: it will flag that trade-offs are missing but cannot assess whether the trade-offs that are present are the right ones. In regulated or safety-critical domains, always pair the prompt's output with human review and consider requiring explicit sign-off on any high-severity findings before the ADR is accepted. For teams with an existing ADR template, adapt the [PATTERN_LIBRARY] placeholder to include your organization's specific anti-patterns and examples drawn from past review failures.

This prompt template is designed to be copied directly into your AI harness, IDE, or evaluation pipeline. It uses square-bracket placeholders that you must replace with your actual ADR text, review criteria, and output format requirements before sending to the model. The template is structured to produce a consistent, machine-readable flagged-issue report that your application can parse, log, and route for human review.

textCopy
You are an architecture review assistant trained to detect common anti-patterns in Architecture Decision Records (ADRs). Your task is to analyze the provided ADR and identify failure modes that undermine decision quality.

## INPUT
[ADR_TEXT]

## PATTERN LIBRARY
Use the following pattern definitions to guide your analysis. For each pattern, assign a severity rating of LOW, MEDIUM, HIGH, or CRITICAL based on the risk it poses to decision correctness and system outcomes.

1. DECISION_BY_DEFAULT: The decision is presented as the only viable path without evidence that alternatives were seriously considered. Severity is HIGH if the decision has broad system impact.
2. MISSING_TRADE_OFFS: The ADR states a decision and its benefits but omits costs, downsides, or rejected alternatives. Severity is MEDIUM if the omission hides known risks; CRITICAL if it hides irreversible consequences.
3. UNSTATED_ASSUMPTIONS: The rationale depends on conditions that are not explicitly stated, validated, or assigned an owner. Severity is HIGH if a false assumption would invalidate the decision.
4. RATIONALIZATION_AFTER_THE_FACT: The ADR reads as a justification for a decision already made rather than a balanced evaluation that preceded the choice. Indicators include one-sided evidence and dismissive treatment of alternatives. Severity is CRITICAL.
5. WEAK_RATIONALE: The rationale relies on vague claims ("best practice," "industry standard," "scalable") without concrete evidence, metrics, or context-specific reasoning. Severity is MEDIUM.
6. MISSING_CONTEXT: The ADR lacks essential background such as constraints, stakeholder concerns, or the problem statement that motivated the decision. Severity is HIGH if the missing context makes the decision unreviewable.
7. GOLD_PLATING: The chosen option includes unnecessary complexity, premature optimization, or speculative features not justified by current requirements. Severity is LOW unless the complexity introduces material risk.
8. CONSEQUENCE_BLINDNESS: The ADR describes the decision but omits the consequences—both positive and negative—that follow from it. Severity is HIGH if negative consequences affect other teams or systems.

## CONSTRAINTS
- Only flag patterns you can cite specific evidence for from the ADR text.
- Do not invent patterns not present in the input.
- For each flagged pattern, quote the relevant ADR passage that supports the finding.
- If no patterns are detected, return an empty findings array.
- Do not rewrite or improve the ADR; only report findings.

## OUTPUT_SCHEMA
Return a JSON object with this exact structure:
{
  "adr_title": "string (extracted or 'Untitled')",
  "findings": [
    {
      "pattern": "PATTERN_NAME",
      "severity": "LOW|MEDIUM|HIGH|CRITICAL",
      "evidence": "Direct quote from ADR",
      "explanation": "Why this pattern applies and what risk it creates",
      "suggested_action": "What the author should do to address this finding"
    }
  ],
  "summary": {
    "total_findings": number,
    "critical_count": number,
    "high_count": number,
    "medium_count": number,
    "low_count": number,
    "overall_assessment": "One-sentence summary of ADR quality"
  }
}

To adapt this template, replace [ADR_TEXT] with the full body of the ADR you want to analyze. If your organization uses a different set of anti-patterns, modify the pattern library while preserving the severity scale and evidence-quoting requirement. The output schema is designed for direct ingestion into a review dashboard or CI/CD pipeline—keep the JSON structure stable so downstream validators can parse findings reliably. Before deploying, run this prompt against a golden set of ADRs with known anti-patterns to calibrate detection accuracy and tune the pattern descriptions for your team's writing style.

This prompt is designed to be integrated into a code review or documentation pipeline, not just used as a one-off chat interaction. The primary integration point is a pull request or merge request workflow where ADRs are committed as markdown files. When a new ADR is proposed, the system should automatically run this prompt against the document and attach the resulting flagged-issue report as a non-blocking review comment. This gives architects and reviewers a structured starting point for their human review, rather than requiring them to manually spot anti-patterns from scratch.

For implementation, wrap the prompt in a thin service that accepts an ADR markdown file path or raw text as input. The service should validate the model's output against a strict JSON schema before surfacing results. The expected output schema includes a flagged_issues array where each issue has a pattern_name (matching the pattern library), severity (CRITICAL, HIGH, MEDIUM, LOW), location (section or line reference in the ADR), evidence (quoted text from the ADR), and recommendation. If the model's output fails schema validation, retry once with the validation error included in the prompt context. If it fails again, log the failure and surface a manual review flag rather than silently dropping the analysis. Model choice matters here: use a model with strong reasoning capabilities (such as Claude 3.5 Sonnet or GPT-4o) because detecting rationalization-after-the-fact and unstated assumptions requires inferring what is not written, not just pattern-matching surface text.

For teams with an existing ADR repository, batch processing is a common pattern. Run the prompt across all existing ADRs to establish a baseline anti-pattern inventory, then run it incrementally on new or modified ADRs. Store results in a database with fields for ADR filename, commit hash, detection timestamp, and issue details. This enables trend analysis—are certain anti-patterns recurring across the team? Are severity levels decreasing over time as the team internalizes the feedback? Avoid using this prompt as a hard gate that blocks ADR merges. False positives are common, especially for MEDIUM and LOW severity detections. Instead, use it as an advisory signal that prompts a human reviewer to look closer at specific sections. The highest-value integration is surfacing CRITICAL issues (like decision-by-default with no alternatives documented) directly in the PR comments where they are hardest to ignore.