ADR Assumption Documentation Prompt

Use this prompt when a team is finalizing an Architecture Decision Record (ADR) and needs to surface implicit assumptions before the decision is approved and implemented. The primary job-to-be-done is risk reduction: unstated assumptions are a leading cause of architectural regret because they turn into broken contracts, unexpected constraints, and costly reversals when proven false. The ideal user is an engineering lead, architect, or technical decision maker who has a draft ADR with a clear decision, options, and trade-offs, but recognizes that the team's shared context may contain blind spots. The prompt requires a draft ADR as input, along with any relevant system context, constraints, and stakeholder notes.

This prompt is not a substitute for the ADR itself. Do not use it to generate the decision, options, or rationale from scratch—use the ADR Generation Prompt Template for that. It is also not a general risk assessment tool; if you need a full risk register with likelihood and impact scoring, use the ADR Risk Assessment Prompt instead. Avoid this prompt when the decision is trivial, the system context is fully known and static, or the team has no authority to validate the surfaced assumptions. The output is an assumption log, not a decision document, and it requires follow-up: each assumption must be assigned an owner, a validation method, and an expiration condition before the ADR is accepted.

After running this prompt, review the assumption log with the full team. Flag any assumption that would invalidate the decision if proven false. Assign owners and deadlines for validation. If the log surfaces assumptions that require changes to the decision, options, or constraints, return to the ADR draft and revise before proceeding. The goal is not to document assumptions for documentation's sake—it is to prevent decisions from being built on foundations that haven't been checked.

This template is designed to be dropped into a prompt harness or used directly in a model playground. It forces the model to surface implicit assumptions—the unstated beliefs that, if proven false, would invalidate the decision. The output is a structured assumption log with validation criteria, owners, and expiration conditions. Adapt the placeholders to match your ADR format, risk tolerance, and review workflow.

textCopy
You are an architecture reviewer specialized in identifying hidden assumptions in technical decisions. Your task is to extract, document, and assess every assumption embedded in the provided architecture decision record (ADR) draft.

## INPUT
[ADR_DRAFT]

## ADDITIONAL CONTEXT
[PROJECT_CONTEXT]
[STAKEHOLDER_LIST]
[CONSTRAINT_LIST]

## INSTRUCTIONS
1. Read the ADR draft and identify every assumption—explicit or implicit—that the decision depends on.
2. For each assumption, determine what would happen if it were false. If the decision would still stand, it is not a critical assumption.
3. Classify each assumption by type: Technical, Business, Organizational, Market, or Regulatory.
4. Assign a criticality rating: Critical (decision invalid if false), High (significant rework required), Medium (adjustment needed), Low (minor impact).
5. For Critical and High assumptions, propose a validation method and an owner.
6. Identify any missing assumptions—beliefs that should be stated but are absent from the draft.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "decision_id": "string",
  "assumptions": [
    {
      "id": "ASM-001",
      "statement": "string (clear, falsifiable statement)",
      "type": "Technical | Business | Organizational | Market | Regulatory",
      "criticality": "Critical | High | Medium | Low",
      "source": "explicit | implicit | missing",
      "if_false_impact": "string (concrete consequence)",
      "validation_method": "string | null (required for Critical and High)",
      "owner": "string | null (role or name)",
      "expiration_condition": "string | null (event that would trigger re-validation)"
    }
  ],
  "missing_assumptions_summary": "string (summary of gaps found)",
  "overall_risk_assessment": "string (assessment of assumption health for this decision)"
}

## CONSTRAINTS
- Every assumption statement must be falsifiable. Avoid vague language like "the system will perform well."
- Do not invent assumptions that are not present or logically required by the ADR.
- If the ADR contains no assumptions, state that explicitly and explain why that is itself a risk.
- For regulated contexts, flag assumptions that touch compliance, data residency, or auditability.
- Limit the output to 20 assumptions maximum. Prioritize by criticality.

## RISK LEVEL
[RISK_LEVEL: low | medium | high]
- If RISK_LEVEL is high, require human review before the assumption log is accepted.
- If RISK_LEVEL is high, add a "reviewer_notes" field to each Critical assumption.

Adaptation guidance: Replace [ADR_DRAFT] with the full text of the decision record. Use [PROJECT_CONTEXT] to inject system diagrams, team structure, or business constraints that the ADR author assumed but did not state. [STAKEHOLDER_LIST] helps the model identify organizational assumptions about who owns what. [CONSTRAINT_LIST] provides explicit boundaries (budget, timeline, compliance) so the model can detect when the ADR silently violates a known constraint. The [RISK_LEVEL] placeholder controls whether the output includes reviewer notes and whether the harness should block automated acceptance. For CI/CD integration, parse the criticality field and fail the pipeline if any Critical assumption lacks a validation_method or owner.

This prompt is designed to be integrated into a structured Architecture Decision Record (ADR) workflow, not used as a one-off chat interaction. The primary integration point is immediately after a draft ADR is written and before it enters peer review. The harness should extract the draft ADR text, the original problem context (meeting notes, design docs, incident reports), and a list of known organizational constraints, then pass them as [DRAFT_ADR], [SOURCE_CONTEXT], and [ORGANIZATIONAL_CONSTRAINTS] respectively. The model's output—a structured assumption log—should be treated as a review artifact that is attached to the ADR, not as a replacement for human judgment. The assumption log becomes a living document that the team revisits when any listed assumption's expiration condition is triggered.

For application wiring, implement a validation layer that parses the model's JSON output and checks for required fields: assumption_id, statement, validation_criteria, owner, expiration_condition, and impact_if_false. If any assumption object is missing a required field, or if the impact_if_false field does not contain a severity classification (BLOCKING, HIGH, MEDIUM, LOW), trigger a retry with a more explicit error message appended to the [CONSTRAINTS] input. Log every assumption extraction run with the ADR version, the model used, the raw output, and the validation result. For high-risk domains such as security architecture or compliance-critical systems, route the assumption log to a human reviewer queue before it is accepted. The reviewer should confirm that no hidden assumptions were missed and that the severity classifications are accurate.

Model choice matters here. Use a model with strong reasoning capabilities (such as GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) because the task requires counterfactual thinking—identifying what is not stated but must be true. Smaller or faster models often miss implicit assumptions or produce shallow validation criteria. Do not use this prompt with a model that lacks structured output support; the assumption log must be machine-readable for downstream tooling. If your ADR workflow includes a CI/CD gate, integrate the assumption log's validation score as a quality check. For example, block ADR merge if any BLOCKING assumption lacks a named owner or if the total count of unowned assumptions exceeds a threshold. Finally, store the assumption log in a queryable format (such as a tagged field in your ADR repository) so that teams can search for all assumptions that will expire within a given timeframe or that depend on a specific external system.