Context Extraction Prompt for ADR

This prompt is for architects and engineering leads who need to extract a structured problem context from unstructured source material—meeting notes, design docs, incident reports, or Slack threads—before drafting an Architecture Decision Record (ADR). The job-to-be-done is converting messy, implicit, and scattered information into a single, reliable context summary that captures the problem statement, known constraints, stakeholder concerns, and assumptions. Without this step, ADRs often start with an ill-defined problem, leading to decisions that solve the wrong thing or ignore critical constraints.

Use this prompt when you have raw source material that contains the why behind a pending architectural decision but no structured summary. It works best when the source material includes discussions of trade-offs, non-functional requirements (latency, cost, compliance, operability), or explicit disagreements between stakeholders. The prompt is designed to produce a completeness-checked output that flags missing constraint categories—such as security, cost, team capability, or regulatory requirements—so you know what to go investigate before writing the ADR. Do not use this prompt when you already have a well-structured problem statement, when the decision is trivial with no trade-offs, or when you need a final ADR document (use the ADR Generation Prompt Template for that).

This prompt is a pre-ADR extraction step. It assumes you will review the output, fill gaps, and then feed the structured context into a downstream ADR generation or drafting workflow. In high-risk or regulated environments, always have a human architect validate the extracted constraints and stakeholder concerns before they become the foundation of a recorded decision. The output is a working document, not an approved artifact. If the source material contains conflicting statements, the prompt will surface them rather than resolve them—resolution is a human judgment call.

This prompt template is designed to extract the problem context, constraints, and stakeholder concerns from raw source material such as meeting notes, design documents, or incident reports. It produces a structured summary that can be directly fed into an ADR generation workflow. The template uses square-bracket placeholders for all variable inputs, allowing you to swap in different source documents, constraint categories, and output schemas without rewriting the core instruction set.

textCopy
You are an architecture analyst extracting structured context for an Architecture Decision Record (ADR).

Your task is to read the provided source material and extract the problem context, explicit and implicit constraints, stakeholder concerns, and any assumptions that should be documented before a decision is made.

## INPUT
[SOURCE_MATERIAL]

## CONSTRAINT CATEGORIES TO CHECK
[CONSTRAINT_CATEGORIES]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "problem_statement": "A concise, one-paragraph description of the problem or decision to be made.",
  "context": {
    "background": "Relevant history, prior decisions, or system state that frames the problem.",
    "trigger": "What event, deadline, or observation prompted this decision now.",
    "scope": "What is in scope and out of scope for this decision."
  },
  "constraints": [
    {
      "category": "One of the provided constraint categories.",
      "description": "The specific constraint identified.",
      "source": "Quote or reference from the source material.",
      "explicit": true_or_false
    }
  ],
  "stakeholders": [
    {
      "role": "Team, system, or person affected.",
      "concern": "What they care about or risk they face.",
      "source": "Quote or reference from the source material."
    }
  ],
  "assumptions": [
    {
      "statement": "The assumption being made.",
      "validation": "How this assumption could be verified or falsified.",
      "risk_if_false": "What breaks if this assumption is wrong."
    }
  ],
  "completeness_notes": {
    "missing_categories": ["Constraint categories with no evidence found."],
    "low_confidence_areas": ["Topics where the source material is ambiguous or silent."]
  }
}

## INSTRUCTIONS
1. Extract only what is present in the source material. Do not invent constraints or stakeholders.
2. For each constraint, identify whether it is explicitly stated or implicitly present in the discussion.
3. Flag any constraint categories from the provided list that have no evidence in the source material.
4. If the source material is ambiguous on a point, note it in completeness_notes rather than guessing.
5. Quote the source material directly when providing source references.
6. If the source material is insufficient to produce a meaningful extraction, return {"error": "INSUFFICIENT_SOURCE", "detail": "explanation"}.

To adapt this template, replace [SOURCE_MATERIAL] with the raw text you need to analyze. Replace [CONSTRAINT_CATEGORIES] with a comma-separated list of categories relevant to your domain, such as performance, security, cost, team capability, compliance, timeline, operational burden, vendor dependency. The output schema can be extended with additional fields, but avoid removing the completeness_notes section—it is the primary mechanism for detecting when the source material is insufficient and preventing hallucinated context from entering your ADR pipeline. For high-risk domains, always route outputs with low_confidence_areas or missing_categories to a human reviewer before using them in a decision document.

The Context Extraction prompt is designed to be the first stage in a multi-step ADR pipeline. It should be called before any generation or review prompt, consuming raw meeting notes, design docs, or incident reports and producing a structured context object. In a production harness, treat this prompt as a precondition gate: if the extracted context fails completeness checks, the system should not proceed to ADR generation. Instead, it should return a structured gap report to the user, requesting the missing information before continuing.

Wire the prompt into your application as an async pipeline step. The recommended flow: (1) Accept raw input text and optional metadata (source type, date, author). (2) Call the LLM with the prompt template, passing [RAW_INPUT] and [CONSTRAINT_CATEGORIES] (use a default set: performance, security, cost, timeline, team capability, compliance, operational burden, and dependencies). (3) Parse the JSON output and validate it against the expected schema—check that all required fields (problem_statement, constraints, stakeholders, assumptions, known_unknowns) are present and non-empty. (4) Run a completeness evaluator: if any constraint category from the input list is missing from the output, flag it. If known_unknowns is empty but the input contains ambiguous or conflicting statements, flag it. (5) If validation passes, store the structured context and proceed to ADR generation. If validation fails, return the gap report to the user with specific prompts for what's missing.

For model choice, prefer a model with strong instruction-following and structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature low (0.0–0.2) to maximize extraction consistency. Implement a retry strategy with up to 2 retries on schema validation failure, appending the validation error to the next attempt's prompt as [PREVIOUS_ERROR]. Log every extraction attempt—including raw input hash, output, validation results, and retry count—for observability. For high-stakes architectural decisions (compliance-critical systems, safety-sensitive domains), add a human review step after extraction: present the structured context alongside the raw source in a review UI, require explicit approval before the context is used for ADR generation, and record the reviewer's identity and timestamp in the audit trail.

Avoid wiring this prompt directly into a synchronous user-facing chat interface. The extraction step benefits from batch or async processing because raw inputs can be long, validation may require multiple retries, and human review gates introduce latency. Instead, expose it through an API endpoint or queue-based worker that returns a job ID and status. The downstream ADR generation prompt should consume only the validated, approved context object—never the raw input directly. This separation of concerns prevents hallucinated context from contaminating the decision record and makes each pipeline stage independently testable and debuggable.