Agent Side-Effect Conflict Detection Prompt

This prompt is designed for reliability engineers and platform operators who manage multi-agent systems where agents are authorized to perform side-effect operations—writes to databases, API calls that mutate state, file system changes, or configuration updates. The core job-to-be-done is to prevent destructive overlaps: a scenario where two or more agents, operating concurrently, attempt to mutate the same resource, leading to data corruption, lost updates, or reconciliation debt. The ideal user is an engineer building an orchestration harness who needs a pre-execution safety check, not a post-hoc audit tool.

Use this prompt when you have a set of pending tool calls or state mutations from multiple agents that are about to be dispatched. The prompt requires a structured input containing each agent's proposed action, the target resource identifier, the operation type, and the proposed new state or payload. It is most effective when integrated into a dispatch loop where the model acts as a gate: analyze the batch, flag conflicts, and recommend a resolution (e.g., serialize, abort one, or request human arbitration). This is not a prompt for detecting semantic task duplication (use the Duplicate Task Detection Prompt for that) or for post-execution auditing (use the Agent Redundancy Audit Prompt). It is specifically for side-effect conflict detection immediately before execution.

Do not use this prompt when agents are performing read-only operations, when the system already enforces strict resource locking at the infrastructure level, or when the mutation target is an append-only log with no risk of destructive overlap. It is also inappropriate for single-agent systems or for workflows where the cost of a conflict is negligible. Before deploying, ensure you have a reliable mechanism for extracting the target resource identifier from each agent's tool call—this prompt's accuracy depends entirely on the quality of that extraction. Pair this with the Idempotency Key Generation Prompt if your system supports idempotent retries, and always log conflict detection events for traceability.

This prompt template is designed to sit inside an orchestration layer that collects pending tool calls, state mutations, or resource claims from multiple agents before execution. It compares the target resources, mutation types, and timing windows to identify conflicts that would cause data corruption, lost updates, or contradictory state changes. The template uses square-bracket placeholders so you can wire it into your existing agent harness without rewriting the conflict detection logic.

codeCopy
You are a side-effect conflict detector for a multi-agent system. Your job is to analyze a set of pending tool calls and state mutations from multiple agents and identify conflicts where two or more agents would write to the same resource in ways that are incompatible.

## INPUT

[PENDING_OPERATIONS]

Each operation includes:
- agent_id: the agent that issued the operation
- operation_id: unique identifier for this operation
- resource_type: the type of resource being modified (e.g., database_row, file, api_resource, state_key)
- resource_id: the unique identifier of the specific resource instance
- operation: the type of mutation (e.g., write, update, delete, append, lock, claim)
- proposed_value: the value or state the agent intends to write (if applicable)
- timestamp: when the operation was queued
- priority: the priority level of the operation (e.g., critical, high, normal, low)

## CONFLICT RULES

Two operations conflict when ALL of the following are true:
1. They target the same resource_type AND resource_id
2. At least one operation is a write, update, delete, or lock (reads do not conflict with each other)
3. The operations would produce incompatible states if both executed

Specific conflict patterns to detect:
- Write-Write: two agents writing different values to the same resource
- Write-Delete: one agent writing while another deletes the same resource
- Delete-Delete: two agents deleting the same resource (wasteful but flag as low-severity)
- Lock contention: two agents attempting to acquire an exclusive lock on the same resource
- Claim conflict: two agents claiming ownership of the same task or workstream
- Append conflict: two agents appending to an ordered resource where order matters

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "conflicts_found": boolean,
  "conflicts": [
    {
      "conflict_id": "string, unique identifier for this conflict",
      "severity": "critical | high | medium | low",
      "conflict_type": "write-write | write-delete | delete-delete | lock-contention | claim-conflict | append-conflict",
      "resource": {
        "resource_type": "string",
        "resource_id": "string"
      },
      "involved_operations": [
        {
          "operation_id": "string",
          "agent_id": "string",
          "operation": "string",
          "proposed_value": "string or null"
        }
      ],
      "description": "string, human-readable explanation of the conflict",
      "recommended_resolution": "string, one of: serialize (execute in order), reject-lower-priority, merge-values, escalate-to-human, acquire-lock-first, no-action (for low-severity duplicates)"
    }
  ],
  "safe_operations": ["operation_id strings that have no conflicts"],
  "analysis_notes": "string, any additional observations about the operation set"
}

## CONSTRAINTS

[CONSTRAINTS]

- If no conflicts are found, return an empty conflicts array and set conflicts_found to false
- Do not flag read-only operations as conflicting with each other
- For write-write conflicts, compare proposed values; if they are identical, downgrade severity to low and note it as a duplicate
- Respect operation priority when recommending resolutions
- If a resource has a defined ownership or locking mechanism, check whether the operations respect it
- Flag any operation that targets a resource outside the agent's declared scope

## EXAMPLES

[EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

If RISK_LEVEL is "high", require human review for all critical-severity conflicts. If RISK_LEVEL is "medium", auto-resolve low-severity conflicts but escalate high and critical. If RISK_LEVEL is "low", auto-resolve all conflicts using the recommended resolution strategy and log the decisions.

To adapt this template, replace [PENDING_OPERATIONS] with the actual operation queue from your agent orchestration layer. The [CONSTRAINTS] placeholder should contain domain-specific rules about resource ownership, locking semantics, and agent scope boundaries. Use [EXAMPLES] to provide 2-3 annotated conflict scenarios that match your system's typical failure patterns. Set [RISK_LEVEL] based on the blast radius of a conflict: use "high" when conflicts could corrupt production data, "medium" for internal state that can be rebuilt, and "low" for non-critical resources where automated resolution is safe. Always validate the output JSON against the schema before acting on conflict resolutions, and log every conflict detection decision for audit trails.

This prompt operates as a pre-execution safety gate inside an agent orchestration loop. Before any agent is allowed to execute a tool call that mutates external state—such as writing to a database, updating a ticket, or modifying a file—the orchestrator collects all pending tool calls from all active agents and passes them through this prompt. The model returns a structured conflict analysis that the harness uses to decide whether to allow, block, or queue each mutation. The prompt is not a standalone classifier; it is a decision-support component that must be wrapped in deterministic validation, logging, and fallback logic.

Wiring pattern: The harness should call this prompt inside a pre_execute_hook that fires after tool selection but before tool invocation. Collect the full set of pending tool calls across agents, serialize them into the [PENDING_TOOL_CALLS] placeholder as a JSON array with fields agent_id, tool_name, target_resource, proposed_change, and timestamp. Include the [RESOURCE_LOCK_STATE] placeholder with current lock ownership, expiry, and queue position for each resource. The model output must conform to a strict JSON schema: an array of conflict objects with conflict_id, resource, agents_involved, conflict_type (one of write-write, read-write, lock-contention), severity (blocking, warning, info), and recommended_action (block, queue, allow, escalate). Validate this schema before acting on any recommendation. If validation fails, retry once with a stricter schema reminder; if it fails again, escalate all pending tool calls to a human operator and log the raw output.

Model choice and latency budget: Use a fast, instruction-following model (GPT-4o or Claude 3.5 Sonnet) with temperature=0 and response_format set to JSON mode. The prompt must complete within your orchestration loop's latency budget—typically under 2 seconds for up to 50 pending tool calls. If latency exceeds this threshold, implement a progressive safety fallback: allow only read-only tool calls to proceed, queue all write calls, and trigger an async conflict analysis that resolves before the queue drains. Log every conflict detection result with the full input payload, model output, validation result, and final harness decision. These logs become your audit trail for debugging false positives (unnecessary blocking) and false negatives (missed conflicts that caused data corruption).

Human review integration: For any conflict with severity: blocking or recommended_action: escalate, the harness must not proceed automatically. Route the conflict to a review queue with the full context: the conflicting tool calls, the model's analysis, and a structured approval payload. The human reviewer's decision (allow, block, or override) should be logged and optionally fed back as a few-shot example in future conflict detection calls to improve accuracy. Avoid: relying solely on the model's severity classification without deterministic resource lock checks. Always cross-reference the model's output against your system's actual lock state—if the model flags a conflict on a resource that your lock manager shows as free, log the discrepancy and prefer the lock manager's ground truth.