Feedback-to-Trace Mapping Prompt

This prompt is your first diagnostic tool when a user reports an issue and you need to find the exact production trace that corresponds to their session. Before you can diagnose a retrieval gap, a tool-call failure, or a model hallucination, you must identify which trace to inspect. The prompt takes structured feedback data—timestamps, user ID, complaint description, and severity—alongside a set of candidate trace summaries, then outputs a ranked mapping with confidence scores and alignment evidence. This workflow assumes you already have a trace observability system that can return candidate traces filtered by user and time window. If your observability platform supports querying by user_id and a timestamp range, you can feed those results directly into this prompt.

The ideal user is a product manager, support engineer, or on-call AI engineer who receives a user complaint and needs to locate the corresponding trace without manually scanning dozens of sessions. The prompt works best when the user feedback includes a rough timestamp (within a 15-minute window), a clear description of the unexpected behavior, and a severity classification. For example, a support ticket stating 'The assistant gave me wrong pricing at 3:45 PM' provides enough signal to narrow candidate traces and rank them by how well the trace events align with the reported issue. The prompt evaluates alignment across multiple dimensions: temporal proximity, semantic similarity between the complaint description and trace events, and the presence of error states or unexpected outputs that match the reported severity.

Do not use this prompt when the user cannot provide a rough timestamp, when your trace system lacks user-level filtering, or when the complaint describes a systemic issue rather than a single session failure. If a user reports 'The assistant has been slow all week,' you need aggregate latency analysis, not session-level trace mapping. Similarly, if your trace retention window has already expired for the reported time period, this prompt cannot help—escalate to a broader investigation of system health metrics. For high-severity issues where the trace mapping will drive an incident response, always pair this prompt's output with human review before treating the top-ranked trace as definitive. The confidence scores are advisory, not authoritative, and a misaligned trace can send your diagnosis in the wrong direction.

After you identify the candidate trace, the next step is to feed it into a dedicated diagnosis prompt—such as the End-to-End Trace Reconstruction Prompt or the Hallucination Source Trace Prompt—depending on the complaint type. This mapping prompt is the entry point, not the full investigation. Keep your feedback intake form structured: require a timestamp, a user identifier, a one-sentence description of what went wrong, and a severity level. That discipline makes this prompt reliable and keeps your diagnosis pipeline moving fast.

This prompt template is designed to reconstruct the relationship between a user's complaint—such as a timestamp, description of unexpected behavior, and severity—and the internal events captured in a production trace. It is a single-turn mapping task. Do not use it in a multi-turn conversation without resetting context, as the model may carry forward assumptions from prior turns that corrupt the mapping logic. The prompt expects you to supply the user feedback details, the raw trace data, and the output schema you want the model to populate. Replace every square-bracket placeholder with real data before execution.

textCopy
You are a trace analysis assistant. Your task is to map a user-reported issue to specific events in a production trace.

## INPUT
User Feedback:
- Timestamp: [USER_REPORTED_TIMESTAMP]
- Description: [USER_COMPLAINT_DESCRIPTION]
- Severity: [USER_REPORTED_SEVERITY]
- User ID: [USER_ID]
- Session ID: [SESSION_ID]

Production Trace:
[RAW_TRACE_DATA]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "mapping_report": {
    "session_id": "string",
    "user_feedback_summary": "string",
    "correlated_events": [
      {
        "trace_span_id": "string",
        "event_type": "string",
        "timestamp": "string",
        "correlation_confidence": "high|medium|low",
        "correlation_rationale": "string",
        "event_details": {}
      }
    ],
    "uncorrelated_feedback_signals": ["string"],
    "overall_alignment_score": "high|medium|low",
    "recommended_actions": ["string"]
  }
}

## CONSTRAINTS
- Only correlate events that have a plausible temporal or semantic link to the user feedback.
- If no trace events match a feedback signal, list it under `uncorrelated_feedback_signals`.
- Do not invent events. Only reference spans present in the provided trace.
- If the trace is incomplete or missing spans, note this in `recommended_actions`.
- Set `correlation_confidence` to `low` if the link is speculative.

## RISK_LEVEL
[RISK_LEVEL]

## EXAMPLES
[EXAMPLES]

To adapt this template, start by replacing [RAW_TRACE_DATA] with the full trace output from your observability platform, ensuring it includes span IDs, timestamps, event types, and payloads. The [USER_REPORTED_TIMESTAMP] should be in ISO 8601 format to enable precise temporal correlation. If your trace data uses a different timestamp format, add a normalization instruction to the [CONSTRAINTS] block. The [RISK_LEVEL] placeholder should be set to high if the user feedback involves a safety incident, billing error, or data loss, which requires human review of the mapping report before any action is taken. For [EXAMPLES], provide one or two few-shot demonstrations showing a user complaint alongside a simplified trace and the expected mapping output. This dramatically improves correlation accuracy, especially for ambiguous feedback descriptions. After generation, validate that every trace_span_id in the output exists in the input trace and that timestamps are within a reasonable window of the user-reported time. If the model produces correlations with low confidence, flag them for human review rather than treating them as definitive.

The Feedback-to-Trace Mapping Prompt is not a standalone script; it is a component that fits inside a larger observability pipeline. When a user reports an issue—via a support ticket, a thumbs-down rating, or an in-app feedback form—the system must first enrich that feedback signal with structured metadata (timestamp, session ID if available, user ID, feedback category, severity, and free-text description) before invoking this prompt. The prompt's job is to take that enriched feedback payload and a set of candidate production traces, then output a ranked mapping report that correlates the complaint to specific trace events. This mapping becomes the entry point for downstream diagnosis: once a trace is identified, other playbooks in this pillar—such as the Tool-Call Sequence Diagnosis Prompt or the Hallucination Source Trace Prompt—can take over for root-cause analysis.

To wire this into an application, build a service function that accepts a feedback_event object and a trace_candidates array. The function should first validate that the feedback event contains at minimum a timestamp, a user_id or session_id, and a description. Traces should be pre-filtered to a reasonable time window around the feedback timestamp (e.g., ±15 minutes) and scoped to the same user or session. Pass these validated inputs into the prompt template as [FEEDBACK_EVENT] and [TRACE_CANDIDATES]. The model should return a JSON object matching the [OUTPUT_SCHEMA] defined in the prompt: a mappings array of candidate traces with trace_id, confidence_score, matched_events, and rationale, plus a review_required boolean and unmatched_signals array. After receiving the response, validate the JSON structure with a schema validator. If parsing fails, retry once with the error message appended to the prompt as additional context. If the review_required flag is true or the top confidence score falls below a configurable threshold (e.g., 0.7), route the mapping to a human reviewer before accepting it as the linked trace.

Logging and observability are critical at every step. Emit structured logs containing the feedback ID, the number of candidate traces evaluated, the top-mapped trace ID, the confidence score, and whether human review was triggered. Store the full prompt request and response in an audit table for later traceability. For high-severity feedback events—such as those involving safety concerns, PII exposure, or regulatory risk—consider requiring mandatory human approval regardless of confidence score. Avoid the temptation to auto-link feedback to traces without this mapping step; timestamp proximity alone is a weak signal in high-throughput systems where multiple traces can occur within seconds. The prompt's real value is its ability to correlate semantic content from the user's description with trace events, tool calls, and model outputs, producing a defensible link that holds up under audit.