Stale State Detection and Correction Prompt Template

This prompt is for agent runtimes that maintain an internal representation of the world—task progress, tool outputs, user preferences, or environmental facts—and need to detect when that representation has diverged from ground truth. The job-to-be-done is comparing a believed state (what the agent thinks is true) against an observed state (fresh evidence from tools, user input, or environment checks) and producing a structured diff with correction actions. The ideal user is an engineering team building autonomous or semi-autonomous agents that operate over multiple turns, where stale state causes repeated work, dropped subtasks, or confident but incorrect decisions.

Use this prompt when your agent has a stored state object that persists across tool calls or conversation turns, and you have a mechanism to re-observe ground truth—such as re-reading a file, re-querying an API, or asking the user for confirmation. The prompt is designed for reconciliation loops: periodic checks, post-tool-failure recovery, session resumption, and handoff validation. It works best when the believed state and observed state share a common schema, making diff generation straightforward. Wire this into a state management module that triggers the prompt on a schedule, after tool errors, or when confidence scores drop below a threshold.

Do not use this prompt for initial state construction from raw observations—that belongs to extraction and normalization prompts. Avoid it when the state is purely conversational and has no external ground truth to check against. This prompt is also inappropriate for real-time control systems where latency constraints prevent a full diff cycle. For high-risk domains where incorrect state could trigger irreversible actions (financial transactions, clinical decisions, infrastructure changes), always route the correction proposal through a human approval step before applying changes. The output diff should be logged as an audit event with the evidence that triggered the correction.

The prompt below is designed to be dropped into an agent runtime whenever a state snapshot must be validated against fresh observations. It forces the model to produce a structured diff—not a narrative summary—so that downstream code can apply corrections deterministically. Use it after tool calls that return new data, before committing to irreversible actions, or when a checkpoint is loaded and must be reconciled with the current environment.

textCopy
You are an agent state auditor. Your task is to compare the agent's BELIEVED STATE with the OBSERVED STATE and produce a structured correction plan.

BELIEVED STATE:
[BELIEVED_STATE]

OBSERVED STATE:
[OBSERVED_STATE]

STATE SCHEMA:
[STATE_SCHEMA]

CONFIDENCE THRESHOLD: [CONFIDENCE_THRESHOLD]

INSTRUCTIONS:
1. Identify every field in the BELIEVED STATE that does not match the OBSERVED STATE.
2. For each mismatch, classify it as one of: STALE (outdated value), MISSING (present in observed but absent in believed), EXTRANEOUS (present in believed but absent in observed), or CONTRADICTORY (both present but conflicting).
3. For each mismatch, propose a CORRECTION ACTION: UPDATE, DELETE, INSERT, or ESCALATE.
4. Assign a CONFIDENCE score (0.0 to 1.0) to each mismatch based on how certain you are that the observed state is correct and the believed state is wrong.
5. If any mismatch has confidence below [CONFIDENCE_THRESHOLD], flag it for HUMAN REVIEW with a specific question that needs resolution.
6. Do NOT propose corrections for fields where the believed and observed values are equivalent after normalization (e.g., "in_progress" vs "IN_PROGRESS", null vs absent).
7. If no mismatches are found, return an empty corrections array with status "CONSISTENT".

OUTPUT SCHEMA:
{
  "status": "CONSISTENT" | "DRIFT_DETECTED" | "CONFLICT_REQUIRES_REVIEW",
  "corrections": [
    {
      "field_path": "string (dot-notation path to the mismatched field)",
      "mismatch_type": "STALE | MISSING | EXTRANEOUS | CONTRADICTORY",
      "believed_value": "any (the value in believed state, or null if missing)",
      "observed_value": "any (the value in observed state, or null if missing)",
      "correction_action": "UPDATE | DELETE | INSERT | ESCALATE",
      "proposed_value": "any (the corrected value to apply, or null for DELETE)",
      "confidence": "float between 0.0 and 1.0",
      "requires_human_review": "boolean",
      "review_question": "string (only if requires_human_review is true, else null)",
      "rationale": "string (brief explanation of why this mismatch was flagged)"
    }
  ],
  "summary": "string (one-sentence summary of findings)"
}

CONSTRAINTS:
- Do not hallucinate observed values. Only use data present in OBSERVED STATE.
- Do not flag cosmetic differences (whitespace, casing, equivalent null representations) as mismatches.
- If the OBSERVED STATE is incomplete or ambiguous, set confidence low and escalate rather than guessing.
- The output must be valid JSON conforming exactly to the OUTPUT SCHEMA.

Adaptation guidance: Replace [BELIEVED_STATE] with the agent's current internal state object, typically serialized as JSON. [OBSERVED_STATE] should be the fresh data returned by a tool call, environment probe, or user correction. [STATE_SCHEMA] is a JSON Schema or TypeScript interface describing the expected shape of both states—this helps the model normalize field names and types before comparing. [CONFIDENCE_THRESHOLD] is a float (we recommend 0.7 as a starting point) below which mismatches are escalated for human review rather than auto-applied. If your agent runtime cannot safely apply corrections automatically, set the threshold to 1.0 to force human review on every mismatch.

What to do next: Wire this prompt into your agent's state reconciliation loop. After every tool call that mutates external state, capture the result as [OBSERVED_STATE] and run this prompt before the agent acts on its believed state. Log every correction object—especially those with requires_human_review: true—to your audit trail. If you see frequent false-positive mismatches, tighten the normalization rules in instruction 6 or add a pre-processing step that canonicalizes both states before comparison. Avoid running this prompt on every turn if state is large and changes are rare; instead, trigger it on checkpoint load, tool failure recovery, and before high-cost actions.

The stale state detection prompt is not a standalone utility; it is a state-repair module that sits between the agent's belief state and ground-truth observations. In a production harness, this prompt fires when a discrepancy trigger activates: a tool returns unexpected data, a precondition check fails, a human provides a correction, or a scheduled reconciliation interval elapses. The harness must supply two structured inputs: [BELIEVED_STATE] (the agent's current internal representation) and [OBSERVED_STATE] (fresh evidence from tools, sensors, or human input). Both inputs should share a common schema so the model can produce a meaningful diff rather than a vague narrative. If the schemas differ, add a pre-processing step that normalizes them before calling the prompt.

Validation and retry logic is critical because stale-state corrections can corrupt state if applied incorrectly. After the model returns a diff with correction_actions, run a structural validator that checks: (1) every correction_actions entry references a valid field path in the state schema, (2) confidence scores are present and within 0.0–1.0, (3) evidence_source fields point to actual observation records, and (4) no correction contradicts another correction in the same batch. If validation fails, retry once with the validation errors appended to [CONSTRAINTS]. If the second attempt also fails, escalate to a human reviewer with the raw diff and validation report. For high-risk domains (healthcare, finance, safety-critical operations), require human approval before applying any correction with confidence below 0.85 or any correction that modifies a safety-relevant field.

Model choice and latency budget shape how you deploy this prompt. For low-latency agent loops where state drift detection runs inline before every action, use a fast model (Claude 3 Haiku, GPT-4o-mini) with a strict 2-second timeout and skip the prompt entirely if the state hasn't changed since the last check. For periodic deep reconciliation (every N steps or on session resume), use a more capable model (Claude 3.5 Sonnet, GPT-4o) and allow up to 10 seconds. Log every invocation with the believed state, observed state, raw diff output, validation result, and whether corrections were applied or escalated. This audit trail is essential for debugging agent loops where the same stale state keeps reappearing. Wire the correction application step as an idempotent state merge: apply only corrections that passed validation, record a version increment on the state object, and retain the pre-correction snapshot for rollback if downstream steps fail after the repair.