Human-in-the-Loop Handoff Prompt Template

This prompt is for system integrators and pipeline engineers building the handoff point where an AI extraction pipeline stops and a human reviewer takes over. It takes the raw extraction attempt, per-field confidence scores, and source document context, then produces a structured handoff payload that a review queue or UI can consume directly. Use this when you need a single, auditable artifact that bundles everything a reviewer needs: the extraction results, confidence details, source spans, reviewer instructions, and the expected response schema for the reviewer's decision.

Do not use this prompt for the extraction itself. It assumes extraction and confidence scoring have already occurred upstream. It also assumes you have a review interface or queue system that can ingest the structured payload. The prompt is designed to be the final transformation step before a human interacts with the data, not a replacement for upstream extraction logic. If you need to perform extraction, entity resolution, or confidence scoring, use the dedicated prompts for those tasks earlier in the pipeline.

Before implementing this handoff, confirm that your upstream extraction pipeline produces the required inputs: a complete extraction attempt with per-field values, a confidence score for each field, and a reference to the source document or span. If any of these inputs are missing, the handoff payload will be incomplete and the reviewer will lack the context needed to make an accurate decision. Wire this prompt after your extraction and confidence scoring steps, and before your review queue ingestion logic.

This template generates a complete human-in-the-loop handoff payload. It takes the AI's best-effort extraction, its confidence assessment, and the original source context, then packages everything a human reviewer needs to make a fast, accurate decision. Replace each square-bracket placeholder with data from your extraction pipeline before sending the prompt to the model. The output is a JSON object designed to be consumed by a review queue UI or workflow engine.

textCopy
You are a handoff formatter for a human-in-the-loop extraction pipeline. Your job is to produce a structured handoff payload when the AI extraction confidence falls below the automation threshold.

## INPUTS
- Extracted Record: [EXTRACTED_RECORD_JSON]
- Confidence Details: [CONFIDENCE_DETAILS_JSON]
- Source Context: [SOURCE_CONTEXT_TEXT]
- Escalation Reason: [ESCALATION_REASON_TEXT]
- Reviewer Role: [REVIEWER_ROLE]
- SLA Target: [SLA_TARGET_HOURS]
- Risk Level: [RISK_LEVEL]

## OUTPUT SCHEMA
Return a single JSON object with these fields:
{
  "handoff_id": "string, unique identifier for this handoff",
  "status": "PENDING_REVIEW",
  "priority": "CRITICAL | HIGH | MEDIUM | LOW",
  "sla_deadline_utc": "ISO 8601 timestamp",
  "reviewer_role": "string, the role that should review this",
  "risk_level": "string, from input",
  "escalation_summary": "string, 1-2 sentence summary of why this was escalated",
  "extraction_attempt": {
    "record": "object, the full extracted record from input",
    "confidence_breakdown": [
      {
        "field": "string, field name",
        "value": "string or null, extracted value",
        "confidence": "number 0.0-1.0",
        "threshold": "number, the threshold this field was compared against",
        "passed": "boolean, whether confidence >= threshold",
        "ambiguity_note": "string or null, what was ambiguous about this field"
      }
    ],
    "overall_confidence": "number 0.0-1.0"
  },
  "source_context": {
    "full_text": "string, the original source text",
    "relevant_spans": [
      {
        "span_text": "string, the specific text relevant to extraction",
        "char_start": "number",
        "char_end": "number",
        "linked_fields": ["string, field names this span relates to"]
      }
    ]
  },
  "reviewer_instructions": {
    "task_summary": "string, what the reviewer needs to decide",
    "specific_questions": ["string, concrete questions the reviewer must answer"],
    "resolution_options": ["string, suggested resolution paths"],
    "decision_format": "string, how to record the decision (e.g., ACCEPT/REJECT/CORRECT)"
  },
  "expected_response_schema": {
    "decision": "ACCEPT | REJECT | CORRECT",
    "corrected_fields": "object or null, corrected values if decision is CORRECT",
    "reviewer_notes": "string, required reviewer notes",
    "reviewer_id": "string, identifier of the reviewer",
    "review_timestamp_utc": "ISO 8601 timestamp"
  }
}

## CONSTRAINTS
- Never fabricate confidence values. Use only the [CONFIDENCE_DETAILS_JSON] provided.
- Include all fields from the extracted record in the confidence_breakdown array, even if they passed the threshold.
- relevant_spans must use exact character offsets from [SOURCE_CONTEXT_TEXT]. Do not approximate.
- If [RISK_LEVEL] is CRITICAL, priority must be CRITICAL and SLA deadline must be within 1 hour.
- reviewer_instructions must be specific enough that a domain expert can act without re-reading the full source.
- Do not include any text outside the JSON object.

Adaptation notes: Replace [EXTRACTED_RECORD_JSON] with the full extraction output from your upstream model. [CONFIDENCE_DETAILS_JSON] should contain per-field confidence scores and the thresholds each field was compared against. [SOURCE_CONTEXT_TEXT] must be the exact original text, not a summary, so character offsets remain valid. If your pipeline doesn't track character offsets, remove the relevant_spans section or replace it with paragraph-level references. For high-risk domains, add a [REQUIRED_EVIDENCE] placeholder that forces the model to cite specific source passages before the handoff is considered complete.

The Human-in-the-Loop Handoff Prompt Template is not a standalone prompt—it is a contract between your automated extraction pipeline and your human review queue. The prompt expects a structured input containing the original source text, the AI's extraction attempt, per-field confidence scores, and the threshold rules that triggered the escalation. Its job is to produce a reviewer-ready payload that a human can act on without redoing the AI's work. In production, this prompt sits behind an API endpoint or queue consumer that fires only when a confidence gate fails. Do not call this prompt for records that pass automation thresholds; it is an escalation path, not a general-purpose formatter.

Wire the prompt into your pipeline with a pre-call validation layer that checks: (1) the extraction attempt payload is present and schema-compliant, (2) confidence scores exist for every field that has a threshold rule, (3) the source text span references are valid and non-empty, and (4) the escalation reason is populated. If any of these fail, reject the handoff request before it reaches the model—do not ask the model to fix missing input data. After the model returns the handoff payload, run a post-call structural validator that confirms the output contains all required fields: reviewer_instructions, source_context, extraction_summary, decision_options, and response_schema. If the output fails validation, retry once with a repair prompt that includes the validation errors. If the retry also fails, log the failure and route the raw extraction attempt to a fallback review queue with a flag indicating incomplete handoff formatting.

For model choice, use a model with strong instruction-following and structured output capabilities. The handoff payload must be valid JSON with no markdown wrapping, so set response_format to json_object or equivalent and provide the exact output schema in the prompt's [OUTPUT_SCHEMA] placeholder. If your platform supports tool calling, define the handoff payload as a tool response schema rather than relying on text-format instructions alone—this reduces format drift. For logging and observability, capture the full handoff input, output, validation results, and reviewer action (accept/correct/reject) in your tracing system. This audit trail is essential for calibrating confidence thresholds and proving review coverage to compliance stakeholders.

The most common production failure mode is reviewer context insufficiency: the handoff payload includes the AI's extraction but omits the specific source spans that caused low confidence, forcing the reviewer to re-read the entire document. Prevent this by ensuring the [CONTEXT] placeholder in your prompt template is populated with the exact text spans, not document summaries. A second failure mode is decision option ambiguity—reviewers receive a payload but don't know what actions they can take. The decision_options field must enumerate concrete choices (e.g., accept_extraction, correct_field, reject_record, request_rescan) with the expected response format for each. Test your handoff pipeline end-to-end with synthetic low-confidence records and measure reviewer time-to-decision; if reviewers consistently need more than 60 seconds to understand the context, your handoff payload needs more targeted span highlighting.