Handoff Context Completeness Check Prompt

This prompt is for orchestration engineers and platform builders who need to validate that a handoff payload between two agents contains everything the downstream agent requires to succeed. The job-to-be-done is preventing silent failures, hallucinated completions, and wasted compute that occur when a receiving agent starts work with missing required fields, unresolved dependencies, or stale context. The ideal user is someone integrating a multi-agent pipeline where agents pass structured state—task definitions, partial results, tool outputs, user intent, and session context—across agent boundaries. You should use this prompt as a gate before any handoff executes, especially when the downstream agent has strict input schema requirements or operates in a high-cost or high-risk domain.

This prompt is not a replacement for schema validation at the application layer. If your handoff payload has a fixed JSON schema with required fields that can be checked deterministically, do that in code first and only use this prompt for semantic gaps that static validation cannot catch—such as whether a [PARTIAL_RESULT] field contains enough detail for the next agent to continue, whether an [ASSUMPTIONS] block contradicts known facts, or whether a [USER_INTENT] summary has drifted from the original request. Do not use this prompt when the downstream agent is designed to handle incomplete context gracefully with its own clarification logic, or when the handoff is purely a fire-and-forget log entry that no agent will act on. The prompt adds latency and token cost, so reserve it for handoffs where a completeness failure would corrupt downstream results or require expensive rollback.

Before deploying this prompt, define your handoff schema and identify which fields are truly blocking versus nice-to-have. The prompt template includes a [REQUIRED_FIELDS] placeholder where you list the fields that must be present and non-trivial for the handoff to proceed. Pair this prompt with a deterministic pre-check that verifies field presence and type correctness, then use the LLM check only for semantic completeness—detecting placeholder values, contradictory information, missing rationale, or context that has expired. In high-risk pipelines, route any handoff that scores below your completeness threshold to a human review queue rather than blocking the pipeline indefinitely. Start with a threshold of 90% completeness for production handoffs and adjust based on observed downstream failure rates.

This template is the core of the Handoff Context Completeness Check workflow. It accepts a candidate handoff payload and a target agent specification, then produces a structured completeness report. The prompt is designed to be dropped directly into an orchestration layer—before a handoff is executed—so that incomplete or ambiguous transfers are caught and repaired early. Every placeholder is a square-bracket token that your application must resolve before sending the request to the model.

textCopy
You are a handoff validation agent. Your job is to inspect a candidate handoff payload and determine whether it contains everything a downstream agent needs to complete its task without additional clarification.

## INPUTS

**Handoff Payload:**
[HANDOFF_PAYLOAD]

**Target Agent Specification:**
- Agent Name: [TARGET_AGENT_NAME]
- Agent Role: [TARGET_AGENT_ROLE]
- Required Input Schema: [TARGET_AGENT_INPUT_SCHEMA]
- Required Context Fields: [REQUIRED_CONTEXT_FIELDS]
- Optional Context Fields: [OPTIONAL_CONTEXT_FIELDS]

**Task Context:**
- Original User Intent: [USER_INTENT]
- Upstream Agent Chain: [UPSTREAM_AGENT_CHAIN]
- Risk Level: [RISK_LEVEL]

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "completeness_score": <float 0.0-1.0>,
  "is_ready_for_handoff": <boolean>,
  "missing_required_fields": [<string>],
  "missing_optional_fields": [<string>],
  "unresolved_dependencies": [
    {
      "dependency": <string>,
      "reason_unresolved": <string>,
      "blocking": <boolean>
    }
  ],
  "ambiguous_sections": [
    {
      "field": <string>,
      "ambiguity": <string>,
      "suggested_clarification": <string>
    }
  ],
  "staleness_warnings": [
    {
      "field": <string>,
      "age_indicator": <string>,
      "recommended_action": <string>
    }
  ],
  "remediation_actions": [<string>],
  "confidence_in_assessment": <float 0.0-1.0>
}

## CONSTRAINTS

1. A field is "missing required" only if the target agent specification explicitly requires it and the handoff payload does not contain it or contains a null/empty value.
2. An "unresolved dependency" is a reference to data, decisions, or outputs from upstream agents that are not present in the payload.
3. Flag a section as "ambiguous" when the content is present but could be interpreted in multiple ways by the downstream agent.
4. A "staleness warning" applies when a field contains a timestamp, version, or state indicator that appears outdated relative to the current task context.
5. Set `is_ready_for_handoff` to `true` only when `missing_required_fields` is empty AND no unresolved dependencies are marked `blocking: true`.
6. If `is_ready_for_handoff` is `false`, `remediation_actions` must contain at least one concrete, actionable step.
7. Do not hallucinate missing fields. Only flag what is demonstrably absent or ambiguous based on the provided schemas.
8. If the risk level is "high" or "critical," apply stricter completeness standards: treat all optional fields as required and flag any ambiguity as blocking.

## EXAMPLES

[FEW_SHOT_EXAMPLES]

## OUTPUT INSTRUCTIONS

Return only the JSON object. No markdown fences, no commentary, no additional text.

To adapt this template, replace each square-bracket placeholder with real data from your orchestration layer. [HANDOFF_PAYLOAD] should be the serialized state object from the upstream agent. [TARGET_AGENT_INPUT_SCHEMA] should be a JSON Schema or structured field list that defines what the downstream agent expects. [FEW_SHOT_EXAMPLES] is optional but strongly recommended: include 2–3 annotated examples showing correct completeness reports for both passing and failing handoffs. The [RISK_LEVEL] placeholder accepts values like low, medium, high, or critical and directly controls how strict the validation becomes.

Before deploying this prompt into a production handoff pipeline, pair it with a schema validator that confirms the model's JSON output matches the expected structure. For high-risk workflows—such as financial transactions, clinical handoffs, or security-sensitive agent chains—route any payload where is_ready_for_handoff is false or confidence_in_assessment is below 0.85 to a human reviewer. Do not rely on this prompt alone to block handoffs without a secondary check that the model did not hallucinate missing fields. The next section covers how to wire this prompt into an application harness with retries, logging, and eval gates.

The completeness check prompt functions as a pre-flight gate in your agent orchestration layer. Before passing a handoff payload to a downstream agent, the orchestrator calls this prompt with the serialized payload and the downstream agent's required input schema. The prompt returns a structured completeness report that your harness must parse and act on: if blocking_gaps is non-empty, the handoff is blocked and must be repaired, escalated, or routed to a fallback agent. This is not a best-effort advisory check—it is a binary gate that prevents downstream agents from receiving incomplete context that would cause silent failures or hallucinated completions.

Wire the prompt into your orchestration framework as a synchronous pre-handoff hook. The harness should: (1) serialize the candidate handoff payload to the format expected by the prompt's [HANDOFF_PAYLOAD] placeholder, typically a JSON string; (2) inject the downstream agent's required field schema into [REQUIRED_SCHEMA], expressed as a list of field names with type constraints and mandatory flags; (3) call the model with response_format set to JSON and validate the output against the expected completeness report schema before acting on it. If the model returns malformed JSON or missing required fields in the report itself, retry once with a stricter schema instruction. If the retry also fails, treat it as a blocking gap and escalate to a human operator with the raw payload and schema attached. Log every completeness check result—including the payload hash, schema version, model response, and gate decision—to your agent audit store for traceability.

For high-reliability deployments, implement a dual-read pattern: run the completeness check against both the primary model and a smaller, faster model on the same payload. If the two reports disagree on blocking gaps, escalate for human review rather than trusting either model alone. This is especially important when the handoff payload contains regulated data, financial instructions, or clinical context where a false negative (missing a real gap) could cause downstream harm. Set a timeout of 5–10 seconds for the completeness check; if it exceeds the timeout, treat the handoff as blocked and route to a human-in-the-loop queue with the timeout reason logged. Never silently proceed with a handoff when the completeness gate fails, times out, or returns an unparseable result—the default posture must be to block and escalate.