Architecture Decision Record Generation Prompt Template

This prompt is for tech leads and platform engineers who need to capture architecture decisions retroactively. The core job-to-be-done is converting unstructured, scattered decision-making evidence—such as pull request discussions, commit messages, and design document comments—into a formal, structured Architecture Decision Record (ADR). The ideal user is someone who has already made a technical decision in the flow of development work but has not yet documented it in the team's decision log. The prompt assumes you have access to the original discussion threads and can provide them as the [INPUT] context. It does not replace the need for human review of the generated ADR before it is committed to the decision log.

Use this prompt when you have a high-signal, messy conversation that contains a clear decision, alternatives that were seriously considered, and a rationale that can be extracted. The prompt is designed to work with raw text from GitHub pull requests, Slack threads, RFC documents, or meeting notes. It is not suitable for generating ADRs from a blank slate or a single-sentence decision. The prompt requires enough source material to ground the output in evidence. If the input is too sparse, the model will hallucinate options or rationale that were never discussed. Always provide the full discussion context, including any dissenting opinions, to produce a balanced record.

Do not use this prompt for decisions that are still under active debate, for capturing real-time meeting notes, or for generating architectural diagrams. It is a documentation tool, not a decision-making tool. The output is a draft that must be reviewed by a human who was present for the decision. Before integrating this into a pipeline, ensure you have a validation step that checks for required ADR fields, source links, and the presence of at least two considered options. The next step after generation is to have the decision owner verify the accuracy of the context, options, and rationale, then commit the record to your ADR repository.

This prompt template is designed to be pasted directly into your AI system. It instructs the model to act as a technical lead and generate a structured Architecture Decision Record (ADR) from provided source material. The template uses square-bracket placeholders that you must replace with real values before execution. The core instruction set defines the persona, the strict output schema, and the critical requirement to ground every decision and rationale in the provided evidence.

textCopy
You are a senior technical lead responsible for documenting past architecture decisions. Your task is to generate a single Architecture Decision Record (ADR) from the provided source material.

## SOURCE MATERIAL
[SOURCE_MATERIAL]

## OUTPUT SCHEMA
You must output a single JSON object conforming to the following structure. Do not include any text outside the JSON object.
{
  "title": "A concise, descriptive title for the decision.",
  "status": "One of: Proposed, Accepted, Deprecated, Superseded.",
  "context": "A paragraph describing the problem, the forces at play, and the circumstances that necessitated this decision. Ground this in the source material.",
  "decision": "A clear, direct statement of the decision that was made. Ground this in the source material.",
  "consequences": "A paragraph describing the resulting context after applying the decision. Include both positive and negative consequences. Ground this in the source material.",
  "options_considered": [
    {
      "option": "A brief description of an alternative option.",
      "rationale": "Why this option was not chosen, based on the source material."
    }
  ],
  "evidence_links": [
    "A direct quote or specific reference from the source material that supports this ADR."
  ]
}

## CONSTRAINTS
- Every field in the output must be populated. Use 'N/A' only if information is truly absent from the source material.
- The 'evidence_links' array must contain at least one direct quote or specific reference from the source material for each of the 'context', 'decision', and 'consequences' fields.
- If the source material contains conflicting viewpoints, you must note the conflict in the 'context' field and explain which viewpoint prevailed in the 'decision' field.
- Do not invent information. If the source material is insufficient to generate a complete ADR, output a JSON object with a single key "error" explaining what is missing.

To adapt this template, replace the [SOURCE_MATERIAL] placeholder with the concatenated text of pull request discussions, commit messages, and design document comments. For high-stakes decisions, consider adding a [RISK_LEVEL] constraint to adjust the strictness of the evidence-grounding requirement. Before integrating this into a production pipeline, you should validate the model's output against the JSON schema and run an LLM-as-a-judge evaluation to check for hallucinated evidence.

This prompt is designed to be integrated into a backend service or CI/CD pipeline that processes pull request metadata, commit histories, and design document comments. The primary integration point is a webhook handler triggered by PR merges or a scheduled job that scans repositories for undocumented decisions. The application layer is responsible for assembling the [INPUT] block—extracting PR descriptions, linked issues, commit messages, and relevant design doc threads—before injecting them into the prompt template. Do not pass raw, unfiltered repository data directly to the model; the harness must deduplicate comments, truncate long threads to the most salient exchanges, and strip bot-generated noise to keep the context window focused on human decision-making.

The implementation should enforce a strict output contract. After the model returns the generated ADR, validate the JSON structure against the expected [OUTPUT_SCHEMA] before writing it to the documentation repository. A validation step must check that required fields—title, status, context, decision, consequences, and options_considered—are present and non-empty. For high-stakes architectural decisions, route the generated ADR to a human review queue (e.g., a pull request in the docs/adr directory) rather than auto-committing. Log the prompt version, model used, and validation pass/fail status as metadata on the ADR for auditability. If validation fails, implement a single retry with a repair prompt that includes the schema violation details; if the retry also fails, escalate to a human with the raw context and the failed output attached.

Model choice matters for this workflow. Use a model with strong structured output capabilities and a large context window (e.g., 128K tokens or more) to accommodate lengthy PR discussions and design doc threads. Enable structured output mode or JSON mode if the model provider supports it, and set a low temperature (0.0–0.2) to maximize factual consistency with the source evidence. For teams running this at scale across many repositories, consider batching ADR generation during off-peak hours and caching the extracted context per PR to avoid redundant API calls. The most common production failure mode is evidence hallucination—the model inventing options or rationale not present in the source material—so always pair this prompt with an evidence-grounding eval that checks whether each claim in the ADR can be traced back to a specific comment or commit in the input.