ADR Technology Selection Prompt

This prompt is for architects and engineering leads who need to choose between specific technologies, frameworks, or platforms for a defined need. Use it when you have a clear problem statement, a shortlist of candidate technologies, and you need a structured, defensible evaluation before writing an Architecture Decision Record. The prompt produces a scored evaluation matrix with weighted criteria, evidence from documentation or prototypes, and explicit trade-off rationale. It is designed to move teams from advocacy-driven debates to evidence-weighted comparison, producing output that can be directly adapted into the 'Options Considered' and 'Decision Rationale' sections of a formal ADR.

The ideal input state includes a concrete problem statement with measurable constraints (latency budgets, throughput requirements, operational SLAs, team skill profiles), a shortlist of 2–5 candidate technologies, and access to documentation, benchmarks, or prototype results for each candidate. The prompt works best when criteria are grounded in observable properties—API surface area, community activity, security advisory history, performance under load—rather than subjective preference. If your criteria are purely subjective or your candidates are not yet identified, this prompt will produce weak, rationalization-heavy output that undermines the decision record rather than strengthening it.

Do not use this prompt for early-stage exploration where you have not yet identified candidates, or for decisions where the criteria cannot be grounded in documentation or measurable properties. It is also inappropriate for decisions that are purely architectural pattern choices (e.g., monolith vs. microservices) without specific technology candidates, or for build-vs-buy decisions where the evaluation dimensions differ substantially. For those cases, use the sibling ADR Build vs Buy Decision Prompt or the Trade-Off Analysis prompt instead. After running this prompt, validate the output by checking that every score has an evidence citation, that weights reflect actual stakeholder priorities rather than equal defaults, and that the recommended option's weaknesses are explicitly acknowledged before you commit the decision to your ADR repository.

This template produces a structured technology selection ADR. It forces the model to act as a dispassionate architect, evaluating up to [NUMBER_OF_OPTIONS] candidates against weighted criteria derived from your specific context. The output is a scored matrix with explicit trade-off rationale, not a persuasive essay for a single option. Replace every square-bracket placeholder with concrete values before sending. The more specific your [CONTEXT] and [CONSTRAINTS], the less the model will rely on generic internet sentiment.

textCopy
You are an experienced software architect producing a technology selection Architecture Decision Record (ADR). Your analysis must be evidence-based, dispassionate, and explicit about uncertainty. Do not advocate. Compare.

## CONTEXT
[CONTEXT]

## DECISION DRIVERS
- Functional requirements: [FUNCTIONAL_REQUIREMENTS]
- Non-functional requirements: [NON_FUNCTIONAL_REQUIREMENTS]
- Constraints: [CONSTRAINTS]
- Stakeholder concerns: [STAKEHOLDER_CONCERNS]

## CANDIDATE TECHNOLOGIES
[CANDIDATE_1_NAME]: [CANDIDATE_1_DESCRIPTION]
[CANDIDATE_2_NAME]: [CANDIDATE_2_DESCRIPTION]
[ADD_MORE_CANDIDATES_AS_NEEDED]

## EVALUATION CRITERIA
[CRITERION_1_NAME]: [CRITERION_1_WEIGHT]% — [CRITERION_1_DEFINITION]
[CRITERION_2_NAME]: [CRITERION_2_WEIGHT]% — [CRITERION_2_DEFINITION]
[ADD_MORE_CRITERIA_AS_NEEDED]

## INSTRUCTIONS
1. For each candidate, assign a score of 1-5 for every criterion. 1 = poor fit, 5 = excellent fit.
2. Multiply each score by the criterion weight. Sum to produce a weighted total.
3. For every score of 4 or 5, cite specific evidence: documentation features, benchmark data, community activity, or prototype results. If evidence is unavailable, cap the score at 3 and note the evidence gap.
4. Identify the top two candidates and write a trade-off section comparing them directly. State what each sacrifices relative to the other.
5. Flag any criterion where all candidates score 3 or below as a risk that may require revisiting the problem framing.
6. If any candidate introduces a new constraint not in the original list, call it out explicitly.

## OUTPUT SCHEMA
Return valid JSON matching this structure:
{
  "decision_title": "string",
  "context_summary": "string",
  "evaluation_matrix": [
    {
      "candidate": "string",
      "scores": { "[CRITERION_NAME]": number },
      "weighted_total": number,
      "evidence_citations": ["string"]
    }
  ],
  "trade_off_analysis": {
    "top_candidates": ["string"],
    "comparison": "string",
    "sacrifice_summary": "string"
  },
  "risks_and_gaps": ["string"],
  "new_constraints_introduced": ["string"],
  "recommendation": "string",
  "confidence_level": "high|medium|low",
  "confidence_rationale": "string"
}

## CONSTRAINTS
- Do not invent benchmark numbers. If you lack data, state that explicitly.
- Do not recommend a technology because it is popular. Popularity is only relevant if it directly affects hiring, community support, or ecosystem maturity for this specific context.
- If the evidence is insufficient to distinguish the top candidates, say so. A forced recommendation is worse than an honest tie.

Before wiring this into an application, validate the output JSON against the schema. Common failures include missing evidence_citations for high scores, confidence_level values outside the enum, and trade_off_analysis that reads like advocacy for one candidate. Run a second pass with a review prompt if the confidence level is low or if any criterion shows all candidates scoring 3 or below. For high-stakes selections, route the output to a human architect for sign-off before the ADR is committed to the repository.

The ADR Technology Selection Prompt is designed to operate as a structured evaluation step within a larger architecture review pipeline, not as a standalone chatbot interaction. In a typical implementation, the prompt receives a technology comparison request from an architect or engineering lead, processes it against the provided criteria and evidence, and returns a scored evaluation matrix. The output should be treated as a draft recommendation that requires human review before it becomes an accepted ADR. Wire this prompt into your workflow after the problem context has been defined and the candidate technologies have been enumerated, but before the final decision is documented and committed to the ADR repository.

Input assembly is the first integration concern. The prompt requires several structured inputs that should be collected through your application's UI or API before invocation: [PROBLEM_STATEMENT] describing the architectural need, [CANDIDATE_TECHNOLOGIES] as a list of options to evaluate, [EVALUATION_CRITERIA] with explicit weights (e.g., performance, team expertise, licensing, community health, operational complexity), and [EVIDENCE_SOURCES] such as documentation links, prototype results, or benchmark data. If your system supports RAG, retrieve relevant internal ADRs, incident reports, or engineering standards and inject them as [CONTEXT] to ground the evaluation in organizational constraints. Model choice matters: use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) because the task requires multi-dimensional comparison and explicit trade-off articulation. Lighter models tend to produce shallow matrices or skip criteria.

Output validation is critical before the result enters your ADR pipeline. Parse the model's response against the expected [OUTPUT_SCHEMA]: a JSON object containing a scored_matrix array (each row a technology, each column a criterion with a numeric score and textual justification), a weighted_totals summary, a trade_off_analysis section identifying where the top-scoring option still carries risk, and a recommendation field with explicit confidence level. Implement a validator that checks: (1) all input criteria appear as columns, (2) all candidate technologies appear as rows, (3) every score cell has a non-empty justification, (4) the weighted totals are arithmetically consistent with the stated weights and scores, and (5) the trade-off analysis addresses at least the top two candidates. If validation fails, retry with error feedback: append the validation errors to the prompt as [PREVIOUS_ERRORS] and re-invoke, up to a maximum of two retries before escalating for human completion.

Human review and approval is the final gate. Even when validation passes, the scored matrix is a draft. Present the output in a review interface that highlights: the top recommendation, the closest competitor, criteria where scores are within one point (indicating weak differentiation), and any trade-off flags. Require an architect or tech lead to approve, adjust scores with documented rationale, or reject the evaluation before it becomes an ADR. Log the full prompt, response, validation results, and reviewer actions for audit traceability. This is especially important in regulated environments where technology selection decisions must be defensible. Avoid wiring this prompt directly into automated decision-making without human-in-the-loop approval; the model can surface patterns and structure comparisons, but it cannot own the organizational consequences of choosing a framework or platform that your team will live with for years.