Capability Gap Detection and Escalation Prompt

This prompt is designed for platform engineers and orchestration system architects who manage a fleet of heterogeneous AI agents. The core job-to-be-done is to programmatically determine when a specific agent has reached the boundary of its defined capabilities and must escalate a task rather than attempt it and fail silently or hallucinate. The ideal user is building a reliability layer into an agent mesh, where a 'dispatcher' or 'supervisor' agent needs to introspect a task against a known capability contract and produce a structured handoff decision. The required context includes a clear definition of the current agent's capabilities, the incoming task, and a catalog of available downstream agents or human fallback queues.

Do not use this prompt when the agent's capabilities are so broad that a gap is unlikely, or when the cost of a failed attempt is lower than the cost of escalation. It is also the wrong tool for simple keyword-based routing or for agents that operate in a single, well-defined domain with no fallback options. This prompt is specifically for heterogeneous fleets where a wrong delegation creates reconciliation debt, duplicated work, or a silent failure. It is a pre-execution guard, not a post-hoc error handler. Use it before the agent acts, not after a tool call fails. For post-failure workflows, use the 'Tool Failure Escalation and Recovery Prompt' instead.

Before implementing, ensure you have a machine-readable capability contract for each agent in your fleet. The prompt's effectiveness is directly tied to the quality of the [AGENT_CAPABILITIES] input. A vague capability description will produce vague gap assessments. Start by defining explicit inclusions and exclusions for each agent, and test the prompt against a golden dataset of tasks that should and should not be escalated. The next step is to wire this prompt into your agent's pre-processing hook so that no task reaches an execution loop without first passing this capability boundary check.

This prompt template is designed to be injected into an agent's execution loop when it encounters a task it cannot confidently complete. It forces a structured self-assessment of the agent's own capabilities against the request, identifies the specific gap, and produces a machine-readable handoff payload for an orchestrator. The primary goal is to prevent silent failures or hallucinated completions by making the 'I cannot do this' decision explicit and actionable.

textCopy
You are a capability assessment module for an autonomous agent. Your task is to analyze the current request and your own operational boundaries to determine if you can fulfill it. Do not attempt to partially complete or guess the task if a capability gap exists.

## Request
[USER_REQUEST]

## Your Capabilities
[AGENT_CAPABILITY_MANIFEST]

## Available Specialist Agents
[AVAILABLE_AGENT_CATALOG]

## Instructions
1.  **Gap Analysis:** Compare the [USER_REQUEST] against your [AGENT_CAPABILITY_MANIFEST]. Identify any specific requirements in the request that you cannot satisfy. Classify the gap type as one of: `tool_missing`, `knowledge_gap`, `policy_restriction`, `confidence_below_threshold`, `domain_unsupported`, or `other`.
2.  **Escalation Decision:** If no gap exists, respond with `{"action": "accept"}`. If a gap exists, respond with `{"action": "escalate"}` and populate the escalation payload.
3.  **Target Selection:** If escalating, select the most appropriate target from the [AVAILABLE_AGENT_CATALOG] based on the required capability. If no suitable agent exists, set the target to `human_operator`.
4.  **Context Packing:** Extract the minimum essential context from [USER_REQUEST] and your current session state required for the target to resume the task without repetition. Include the original request, relevant data, and your partial progress, if any.

## Output Schema
Respond exclusively with a valid JSON object. Do not include any text outside the JSON block.
{
  "action": "accept" | "escalate",
  "gap_type": "tool_missing" | "knowledge_gap" | "policy_restriction" | "confidence_below_threshold" | "domain_unsupported" | "other",
  "gap_description": "A concise, specific explanation of what you cannot do and why.",
  "target_agent_id": "[TARGET_AGENT_ID_OR_human_operator]",
  "handoff_payload": {
    "original_request": "[VERBATIM_USER_REQUEST]",
    "session_context_summary": "[RELEVANT_STATE_AND_DATA]",
    "failure_reason_code": "[GAP_TYPE]",
    "recommended_action": "A one-sentence instruction for the target agent."
  },
  "confidence": 0.0
}

To adapt this template, replace the square-bracket placeholders with your system's live data. [AGENT_CAPABILITY_MANIFEST] should be a static, structured description of the agent's tools, knowledge domains, and policy constraints. [AVAILABLE_AGENT_CATALOG] is a dynamic list of other agents and their capabilities, typically fetched from an orchestration service. The handoff_payload must be treated as a contract; the receiving agent or human operator should be able to resume the task using only the information in that object. Before deploying, validate the JSON output against the schema and implement a retry or repair step if parsing fails, as a malformed escalation is a critical failure mode.

This prompt is designed to sit at the boundary of an agent's execution cycle, invoked whenever the agent encounters a task it cannot complete with high confidence. The implementation harness must treat this prompt as a structured decision point, not a free-text suggestion. The output is a machine-readable capability assessment that your orchestration layer parses to route work to the next specialized agent, a human queue, or a graceful degradation path. The harness is responsible for enforcing the output schema, validating gap coverage completeness, and preventing the prompt from being bypassed when the agent's internal confidence falls below a configured threshold.

Integration pattern: Wrap the prompt in a function that accepts the current agent's role definition, the failed or uncertain task description, the agent's self-reported confidence score, and the available downstream agent registry with capability descriptions. The function should call the LLM with response_format set to a strict JSON schema matching the expected output fields: detected_gaps (array of capability shortfalls), recommended_escalation_target (agent ID or human_review), gap_coverage_completeness (boolean), and rationale. After receiving the response, run a validator that checks: (1) every gap in detected_gaps maps to at least one capability in the agent registry, (2) the recommended_escalation_target exists in the registry or is the reserved human_review token, and (3) gap_coverage_completeness is true. If validation fails, retry once with the validation errors injected into the prompt as [PREVIOUS_ERRORS]. If the retry also fails, escalate to a human operator with the raw output and validation trace attached.

Model choice and latency: Use a model with strong instruction-following and structured output support for this prompt. The decision is high-stakes—routing to the wrong agent or failing to detect a gap can cause silent failures downstream. Expect latency in the 1-3 second range for capable models. If your agent loop is sub-second, consider running this check asynchronously after the agent's primary response, with a circuit breaker that halts further autonomous action until the capability assessment returns. Logging and audit: Every invocation must produce a structured log entry containing the input context, the raw model output, the validation result, the final routing decision, and a timestamp. This audit trail is essential for debugging handoff failures and demonstrating governance controls. Human review trigger: When recommended_escalation_target is human_review, the harness must package the capability assessment alongside the original task context and the agent's partial work into a structured handoff payload for your human-in-the-loop queue. Do not silently downgrade a human escalation to an automated fallback.

What to avoid: Do not use this prompt as a replacement for agent-level confidence scoring. The prompt works best when the agent already has a calibrated internal confidence estimate to provide as input. Avoid invoking this prompt on every agent turn—reserve it for low-confidence states, tool failures, or tasks that fall outside the agent's declared capability boundary. Do not skip the validation step; even strong models occasionally produce hallucinated agent IDs or incomplete gap lists. Finally, test the harness end-to-end with a gap coverage eval set: a collection of scenarios where the correct escalation target is known, including edge cases where multiple gaps exist or no suitable downstream agent is available. Measure routing accuracy, false-negative gap detection rate, and validation pass rate before deploying to production.