Internal Code-to-Name Resolution Prompt

This prompt is for enterprise RAG and search teams who need to bridge the gap between how users refer to internal entities and how those entities are indexed. The core job-to-be-done is translating opaque identifiers—such as project codes, ticket numbers, part SKUs, or cost center IDs—into the descriptive names and labels that appear in your knowledge base. The ideal user is a platform engineer or search relevance engineer who maintains a codebook mapping internal codes to canonical names and needs a reliable, auditable resolution step before retrieval. Without this step, a user query like 'status of ATH-4021' will fail against documents that only mention 'Athena Project Phase 2'.

You should use this prompt when your retrieval index is built on human-readable text but your users frequently reference internal codes, IDs, or shorthand in their queries. The prompt requires a provided codebook—a structured mapping of codes to names—as part of the context. It is designed to handle exact matches, partial matches, and obsolete codes with explicit flags. Do not use this prompt when the code-to-name mapping is already handled by a deterministic database lookup in your application layer; a prompt adds latency and cost without benefit in that case. Similarly, avoid this prompt for real-time transactional systems where a failed resolution could block a critical operation without a human in the loop.

The prompt works best as a pre-retrieval step in a RAG pipeline, where its output feeds directly into your query rewriter or search backend. Always validate the output against your codebook to catch hallucinations—the model should never invent a name that does not exist in the provided mapping. For high-stakes domains like finance, healthcare, or compliance, require human review when the prompt flags an obsolete code or returns a low-confidence partial match. The next section provides the copy-ready template you can adapt with your own codebook and output schema.

This prompt template is designed to be dropped into a retrieval pipeline before the search step. It accepts a raw user query and a structured codebook, then outputs a rewritten query with codes replaced by their canonical names. The template uses square-bracket placeholders for all variable inputs, making it straightforward to parameterize in code. The core instruction forces the model to act as a precise resolver: it must only map codes that appear in the provided codebook, flag obsolete or unknown codes, and preserve the original query structure so downstream retrieval is not disrupted by aggressive rewriting.

textCopy
You are an internal code resolver for an enterprise knowledge base. Your job is to identify internal codes, project IDs, ticket numbers, or entity identifiers in a user query and replace them with their human-readable names using the provided codebook.

## CODEBOOK
[CODEBOOK]

## USER QUERY
[USER_QUERY]

## INSTRUCTIONS
1. Scan the user query for any tokens that match codes or identifiers in the codebook.
2. For each matched code, replace it with the corresponding human-readable name from the codebook.
3. Preserve all other words, punctuation, and query structure exactly as written.
4. If a code appears in the query but is marked as [OBSOLETE] in the codebook, replace it with the name but append "(obsolete)" after the name.
5. If a token looks like a code but does not appear in the codebook, leave it unchanged and append "[UNRESOLVED]" immediately after the token.
6. If the query contains partial code fragments that could match multiple entries, do not guess. Leave the fragment unchanged and append "[AMBIGUOUS]" after it.
7. Do not add, remove, or rephrase any content beyond the code substitutions and flags described above.

## OUTPUT FORMAT
Return a JSON object with the following fields:
- "rewritten_query": the query with codes replaced by names and flags applied.
- "resolved_codes": an array of objects, each containing "original_code", "resolved_name", and "status" (one of "resolved", "obsolete", "unresolved", "ambiguous").
- "unresolved_tokens": an array of strings for any tokens that could not be resolved.

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

To adapt this template, replace [CODEBOOK] with a structured representation of your internal codes and names. A JSON array of objects with code, name, and status fields works well. Replace [USER_QUERY] with the raw user input at runtime. Use [CONSTRAINTS] to add domain-specific rules, such as 'never resolve codes shorter than 3 characters' or 'ignore codes inside quotation marks.' Use [EXAMPLES] to provide few-shot demonstrations of correct resolution behavior, including edge cases like obsolete codes and partial matches. Before deploying, validate the output JSON schema in your application layer and log any queries that produce [UNRESOLVED] or [AMBIGUOUS] flags so you can improve the codebook over time.

This prompt is designed to sit between the user's natural language query and your retrieval system. It acts as a pre-retrieval translator, extracting internal codes (like project IDs, ticket numbers, or part SKUs) and mapping them to their canonical, human-readable names using a provided codebook. The output is a rewritten query that replaces opaque codes with descriptive labels, which dramatically improves recall in vector and keyword search indexes that contain the full names but not the shorthand codes. The harness must treat the codebook as the single source of truth; the model is never allowed to invent a mapping that isn't explicitly present in the provided [CODEBOOK] context.

To wire this into an application, build a thin API wrapper that accepts the user's raw query and a JSON codebook payload. The codebook should be a dictionary mapping codes to their canonical names, optionally including an obsolete flag and valid_until date for deprecated codes. Before calling the LLM, validate that the codebook is not empty and that all keys are strings. After receiving the model's response, parse the output against a strict JSON schema that requires a rewritten_query string, a mappings array of objects with code, resolved_name, and confidence fields, and an unresolved_codes array for any codes the model couldn't map. If the output fails schema validation, retry once with the validation error injected into the prompt as a correction hint. If it fails again, log the failure and fall back to the original user query to avoid blocking retrieval. For high-stakes domains like finance or healthcare, route all unresolved codes to a human review queue before the rewritten query is used for retrieval.

Model choice matters here. This task requires precise instruction-following and low hallucination on structured extraction, not creative generation. Prefer models with strong JSON mode support (e.g., GPT-4o, Claude 3.5 Sonnet) and set temperature=0. Enable structured output mode if your provider supports it, binding the response to the schema directly rather than relying on a prompt description alone. Log every mapping event—including the original query, the codebook version used, the resolved mappings, and any unresolved codes—to an observability store. This audit trail is essential for debugging retrieval failures and for maintaining the codebook over time. When you detect a pattern of unresolved codes, feed those back to the team that owns the codebook so they can add missing entries or mark codes as obsolete.