Architecture Decision Intent Query Rewrite Prompt Template

This prompt is designed for a specific job: transforming a user's natural language question about software architecture into a retrieval-optimized query for a RAG system. The ideal user is a developer or architect asking 'should we use X or Y for Z?' or 'what are the trade-offs of pattern A vs. pattern B?'. The required context is a knowledge base containing structured decision rationale, such as Architecture Decision Records (ADRs), design docs, RFCs, and trade-off analyses. The core value is bridging the gap between a conversational question and the precise, consequence-focused language found in these internal documents.

You should use this prompt when your retrieval system needs to surface documents that explain the why behind a choice, not just the what. For example, a user question like 'Is PostgreSQL a good fit for our event-sourcing system?' requires a query that retrieves ADRs discussing database selection, consequences of event sourcing, and rejected alternatives like Kafka or MongoDB. A naive keyword or vector search for 'PostgreSQL event sourcing' will likely return API references or generic blog posts. This prompt detects the architectural evaluation intent and generates a query like 'architectural decision record for database selection in event-sourcing systems, including trade-offs, consequences, and rejected alternatives for PostgreSQL, Kafka, and MongoDB'.

Do not use this prompt for general Q&A over code documentation, API references, or runbook procedures. It is specifically tuned for the language of architectural choice and consequence. If a user asks 'How do I create a table in PostgreSQL?', this prompt is the wrong tool; a procedural intent rewrite or a direct RAG query over documentation would be more appropriate. Using this prompt for non-architectural questions will likely produce an over-engineered query that retrieves irrelevant decision records, leading to poor answer quality and wasted context.

Before integrating this prompt, verify that your knowledge base actually contains the type of documents it's designed to retrieve. If your indexed corpus consists mostly of code comments, API specs, and playbooks, the rewritten queries will not improve retrieval. The next step is to review the prompt template and adapt the architectural concern tags to match your team's specific terminology, such as 'design doc', 'RFC', or 'trade-off memo'.

This template is designed to be placed in your system prompt or a query rewriting module within a RAG pipeline. Its job is to detect when a user is evaluating architectural choices and transform their natural language question into a retrieval-optimized query. The output includes the rewritten query string and a set of architectural concern tags that you can use as metadata filters against a vector or hybrid search index containing Architecture Decision Records (ADRs), design docs, and RFCs.

textCopy
You are a query rewriting agent for a software architecture knowledge base. Your task is to detect when a user's question indicates they are evaluating an architectural choice, comparing design options, or seeking trade-off analysis. If the intent is architectural decision-making, rewrite the query to maximize retrieval of Architecture Decision Records (ADRs), design pattern documentation, trade-off analyses, and technical RFCs. If the intent is not architectural, return the original query unchanged.

### INPUT
User Query: [USER_QUERY]

### OUTPUT SCHEMA
Return a valid JSON object with the following fields:
{
  "intent": "architecture_decision" | "other",
  "rewritten_query": "string",
  "architectural_concerns": ["string"],
  "reasoning": "string"
}

### REWRITING RULES
1. Expand acronyms and normalize architectural terminology (e.g., 'k8s' -> 'Kubernetes', 'event-driven' -> 'event-driven architecture').
2. Include synonyms for key concepts: 'ADR', 'decision record', 'design rationale', 'trade-off', 'consequence', 'alternative considered'.
3. Extract and append explicit architectural quality attributes as keywords: scalability, availability, consistency, latency, maintainability, cost, security, deployability.
4. If the query mentions specific technologies, frameworks, or patterns, include their canonical names and common alternatives.
5. Preserve all original constraints and context from the user query.

### ARCHITECTURAL CONCERN TAGS
Select from the following controlled vocabulary based on the query content:
- scalability
- availability
- performance
- security
- maintainability
- cost
- consistency
- durability
- latency
- deployability
- observability
- testability
- interoperability
- data_management
- integration_pattern
- migration_strategy

### CONSTRAINTS
- Do not hallucinate technologies or constraints not present in the original query.
- If the query is ambiguous about architectural intent, default to 'other' and return the original query.
- The rewritten query must be self-contained and not rely on external conversation context.

To adapt this template, replace [USER_QUERY] with your application's actual user input variable. If your knowledge base uses a different taxonomy for architectural concerns, update the controlled vocabulary list to match your internal tags. For production use, wrap the JSON output in a validation step that confirms the rewritten_query is non-empty and the architectural_concerns array contains only allowed tags. If the model returns "intent": "other", bypass the architecture-specific retrieval index and fall back to your general-purpose search. Always log the reasoning field for debugging false positives where non-architectural queries are misclassified.

This prompt is designed as a pre-retrieval transformation step in a software architecture RAG system. It should sit between the user's raw query and the retrieval engine, intercepting natural language questions about architectural choices and rewriting them to target architecture decision records (ADRs), trade-off analyses, and design pattern documentation. The harness must treat this prompt as a structured transformation function: natural language in, a JSON object containing rewritten_query and architectural_concern_tags out. Do not expose the rewritten query to the end user unless you are building a debug or transparency panel. The output is a retrieval artifact, not a user-facing answer.

Wire this prompt into your application as a synchronous pre-retrieval call. Use a model with strong JSON mode or structured output support (e.g., GPT-4o, Claude 3.5 Sonnet) and enforce the output schema at the API level rather than relying solely on the prompt's format instructions. The expected output shape is: {"rewritten_query": "string", "architectural_concern_tags": ["string", ...], "intent_confidence": 0.0-1.0, "requires_clarification": false}. After receiving the output, validate that rewritten_query is non-empty and semantically distinct from the input (a simple string equality or Levenshtein distance check can catch no-op rewrites). If requires_clarification is true or intent_confidence falls below a configurable threshold (start with 0.7), route to a human clarification step or surface a disambiguation question to the user rather than executing a low-confidence retrieval. Log every rewrite alongside the original query, the detected intent, the confidence score, and the final retrieval metrics for offline evaluation.

For retrieval execution, use the rewritten_query as the primary search string and append the architectural_concern_tags as metadata filters or boosted terms depending on your search backend. If you are using a hybrid vector and keyword index, send the rewritten query to both and apply the concern tags as keyword boosts or filter clauses. Common failure modes to monitor: the prompt may produce a rewritten query that is too narrow and misses relevant ADRs, or it may over-generalize and retrieve design pattern documentation that lacks decision rationale. Mitigate this by implementing a post-retrieval check that scans returned documents for structured decision fields (e.g., 'Decision', 'Rationale', 'Consequences', 'Alternatives Considered'). If fewer than a minimum number of documents contain these fields, fall back to a broader retrieval strategy or append the original query as a secondary retrieval pass. Do not use this prompt for real-time chat where latency must be under 200ms; the rewrite step adds a full model inference round-trip and is best suited for asynchronous or slightly delayed retrieval workflows where decision quality outweighs sub-second response times.

Before shipping, build a regression test suite with 20-30 labeled examples covering clear architecture decision queries ('Should we use event sourcing or CQRS?'), ambiguous queries ('What's the best database?'), and non-architecture queries ('How do I write a for loop?'). Measure rewrite relevance, tag accuracy, and downstream retrieval precision against a golden ADR corpus. Run these tests on every prompt version change. In production, set up a feedback loop: when users rate retrieved documents as unhelpful, capture the original query, the rewritten query, and the retrieved document IDs for periodic prompt tuning. Avoid the temptation to chain multiple intent-detection prompts sequentially; if you need to detect architecture intent alongside other intents, use a single multi-class classification prompt rather than running this prompt in parallel with other intent detectors and then selecting the highest-confidence result.