Definite Description Grounding Prompt

This prompt is designed for multi-turn AI systems—chat assistants, copilots, and task-oriented agents—where users naturally refer back to previously mentioned entities using descriptive phrases instead of repeating exact identifiers. The core job-to-be-done is mapping an under-specified noun phrase like 'the error from this morning' or 'the second option' to a single, concrete entity in the session history. Without this capability, assistants force users into a rigid, command-line style of interaction, breaking the conversational flow. The ideal user is a developer or AI engineer building a product where session context is rich and users expect the system to remember what was discussed.

You should use this prompt when your application maintains a structured or semi-structured session history and users frequently use relational attributes (temporal, ordinal, spatial) to refer back to entities. It is particularly valuable in customer support, where a user might reference 'the last agent I spoke with'; in data analysis copilots, where a user asks to 'plot the second metric'; or in task management, where a user wants to 'update the invoice from Tuesday.' The prompt expects a history of prior turns and a current user utterance as input. It is not a general-purpose entity extractor; it assumes the referent already exists in the provided context. Do not use this prompt for open-world knowledge base linking, for resolving pronouns like 'it' or 'they' (which require a different syntactic approach), or for single-turn commands where no prior context exists.

Before integrating this prompt, you must have a reliable mechanism for capturing and formatting session history. The prompt's effectiveness degrades if the history is truncated, poorly structured, or missing timestamps and ordinal positions that users reference. A common failure mode is deploying this prompt on a system that only retains the last N messages without metadata, making temporal references like 'yesterday's report' unresolvable. Ensure your upstream context assembly pipeline preserves the attributes users are likely to mention. The next step after understanding this use case is to examine the prompt template and adapt its output schema to match your application's entity model.

This template provides the core instruction set for an assistant that must resolve phrases like 'the invoice from Tuesday' or 'the error we discussed' against a structured session history. It is designed to be pasted into your system prompt or user-message template. Replace every square-bracket placeholder with your application's specific data, schemas, and constraints before use. The prompt enforces a strict contract: either return a grounded entity match with evidence, or return a structured clarification request. It must never guess silently.

codeCopy
SYSTEM:
You are a reference resolution module in a multi-turn assistant. Your job is to resolve definite descriptions in the current user turn against the provided [SESSION_HISTORY]. A definite description is a noun phrase that assumes the referent is uniquely identifiable from context (e.g., 'the invoice from Tuesday', 'the error we discussed', 'her last email').

# INPUT
You will receive:
- [CURRENT_USER_TURN]: The latest user message containing a definite description to resolve.
- [SESSION_HISTORY]: A structured array of prior turns, each with a turn ID, speaker, timestamp, and text. The history may also include a [RESOLVED_ENTITY_MAP] of previously grounded entities.

# OUTPUT CONTRACT
Return a single JSON object with exactly one of two shapes:

## Shape 1: Resolved Entity
{
  "status": "resolved",
  "description_phrase": "[the exact phrase from the user turn]",
  "resolved_entity": {
    "entity_id": "[unique ID from RESOLVED_ENTITY_MAP or generated]",
    "entity_type": "[type from ENTITY_TYPES]",
    "canonical_name": "[the grounded name of the entity]",
    "attributes": { /* key-value pairs matching the description */ }
  },
  "grounding_evidence": {
    "source_turn_ids": ["[turn IDs that support this resolution]"],
    "rationale": "[brief explanation of why this entity matches the description]"
  },
  "confidence": 0.0-1.0
}

## Shape 2: Clarification Required
{
  "status": "clarification_required",
  "description_phrase": "[the exact phrase from the user turn]",
  "candidate_entities": [
    {
      "entity_id": "[ID]",
      "canonical_name": "[name]",
      "match_score": 0.0-1.0,
      "why_candidate": "[brief reason this is a candidate]"
    }
  ],
  "clarification_question": "[a single, targeted question that disambiguates the reference without repeating the entire context]",
  "reason_for_clarification": "[ambiguity | no_candidate | low_confidence | temporal_mismatch | attribute_conflict]"
}

# RESOLUTION RULES
1. **Temporal Matching**: When the description includes a temporal attribute (e.g., 'from Tuesday', 'last week'), match it against the timestamp in [SESSION_HISTORY]. If multiple entities match the temporal window, flag for clarification unless another attribute disambiguates.
2. **Relational Matching**: When the description includes a relational attribute (e.g., 'the error we discussed', 'her last email'), use the speaker and topic context from prior turns to identify the correct entity.
3. **Recency Bias**: In the absence of other distinguishing attributes, prefer the most recently mentioned entity of the matching type. Document this assumption in the rationale.
4. **No Silent Guessing**: If no candidate exceeds the confidence threshold of [CONFIDENCE_THRESHOLD], return a clarification request. Never return a resolved entity with confidence below this threshold.
5. **Entity Type Constraints**: Only resolve to entity types in [ENTITY_TYPES]. If the description implies a type not in this list, request clarification.

# CONSTRAINTS
- Do not resolve pronouns (he, she, it, they). This module handles definite descriptions only.
- Do not invent entities not present in [SESSION_HISTORY] or [RESOLVED_ENTITY_MAP].
- The clarification question must be answerable in a single turn (e.g., 'Did you mean the invoice from Tuesday March 12 or Tuesday March 19?').
- If [RISK_LEVEL] is 'high', set [CONFIDENCE_THRESHOLD] to 0.95 and always include a human-review flag in the output.

To adapt this template for your application, start by defining your [ENTITY_TYPES] schema. This should be a closed set of types your system can track (e.g., invoice, support_ticket, error_report, user). Next, implement the [SESSION_HISTORY] and [RESOLVED_ENTITY_MAP] data structures in your application state manager. The history should be a time-ordered array of turns, and the entity map should be a dictionary of previously resolved entities keyed by unique ID. Set [CONFIDENCE_THRESHOLD] based on your domain's tolerance for incorrect resolution: 0.85 for general use, 0.95 for regulated or high-stakes domains. Wire the output into your downstream NLU pipeline: if status is resolved, substitute the canonical_name into the user's utterance before intent classification; if status is clarification_required, surface the clarification_question to the user and pause the pipeline until the next turn resolves it.

The Definite Description Grounding Prompt is a pre-processing step in a multi-turn dialogue pipeline. It should execute before the main reasoning or response-generation prompt, receiving the user's latest utterance and a structured representation of session history. The output is either a grounded entity match (with an entity ID, attribute evidence, and confidence score) or a structured clarification request. This prompt is not a standalone chatbot; it is a state-resolution component that feeds into downstream NLU, RAG retrieval, or tool-calling steps. Wire it as a synchronous call within each turn-processing loop, with a strict timeout (500–1500 ms is typical) because unresolved references block all subsequent processing.

Input assembly requires two data structures: [CURRENT_UTTERANCE] (the raw user text) and [SESSION_ENTITIES] (a JSON array of entities mentioned in prior turns, each with an id, type, attributes map, last_mentioned_turn, and canonical_name). If your application maintains a structured dialogue state or slot store, map it into this entity grid before calling the prompt. For RAG-augmented systems, also include [RETRIEVED_ENTITIES] from the knowledge base that overlap with the session context. Output validation must check: (1) the resolution_status field is exactly grounded or clarification_needed, (2) a grounded result includes a non-empty entity_id that exists in the input entity set, (3) the attribute_evidence array contains at least one matched attribute with a turn reference, and (4) the confidence score is a float between 0.0 and 1.0. Reject and retry any output that fails schema validation. For high-stakes domains (healthcare, finance, legal), route clarification_needed results with confidence < 0.7 to a human review queue rather than auto-clarifying with the user.

Retry logic should be minimal: one retry with the validation error message appended to the prompt as [PREVIOUS_ERROR]. If the second attempt also fails validation, log the raw output and fall back to a safe default—either a generic clarification question or an escalation to human review, depending on the risk level configured in [RISK_LEVEL]. Logging must capture: the input utterance, the resolved entity ID (or clarification flag), confidence score, latency, model used, and any validation failures. This log becomes your primary debugging tool when users report the assistant confusing entities. Model choice: use a fast, instruction-tuned model (GPT-4o-mini, Claude Haiku, or equivalent) for latency-sensitive chat; use a larger model only if your eval suite shows the smaller model failing on temporal attribute matching (e.g., 'the invoice from Tuesday' when multiple Tuesdays exist in session history). Tool integration: if grounding succeeds, pass the resolved entity_id and canonical_name to downstream tool calls or RAG queries as explicit filters, preventing the model from re-resolving the reference later in the turn. What to avoid: do not call this prompt on every user message—skip it for utterances with no definite descriptions (detectable via a lightweight regex or classifier pre-check) to save latency and cost. Do not use the prompt's confidence score as the sole gate for automated actions in regulated workflows; always combine it with application-level business rules and human approval where required.