Deadlock Detection Prompt for Workflow Definitions

This prompt is a pre-flight safety check for CI/CD operators, workflow engine developers, and agent architects who need to validate formal workflow definitions before they are executed. Its primary job is to analyze a provided workflow specification—typically in YAML, JSON, or a domain-specific language (DSL)—and identify structural concurrency hazards that would cause the workflow to stall. These hazards include resource-wait cycles (where Task A waits for a lock held by Task B, which is waiting for Task A), mutex conflicts, and ordering deadlocks. The ideal user is someone responsible for production workflow reliability who wants a fast, LLM-powered linting step to catch these problems before they become incidents requiring manual intervention.

To use this prompt effectively, you must provide a complete, machine-readable workflow definition as the [WORKFLOW_DEFINITION] input. This definition must explicitly declare tasks, their dependencies, and any resource locks or mutexes they acquire. The prompt is not designed to infer dependencies from natural language descriptions or to analyze runtime logs; it performs a static analysis of the declared structure. You should wire this prompt into your deployment pipeline as a gating step, where a failure blocks the workflow from being deployed to production. The output includes a severity classification for each detected deadlock and a recommended resolution, but this guidance should be treated as a suggestion for a human operator to review, not as an automated fix.

Do not use this prompt as a replacement for a formal model checker like TLA+ or a dedicated static analysis tool for your workflow engine. It is a fast, probabilistic safety net, not a proof of correctness. It may miss deadlocks that arise from complex temporal logic, dynamic resource creation, or conditions not fully expressed in the static definition. It is also not suitable for analyzing workflows defined only in natural language or for detecting performance bottlenecks that are not strict deadlocks. In high-risk environments where a stalled workflow could cause significant financial, operational, or safety impact, you must combine this prompt with deterministic validation tools and a mandatory human review step before any workflow is promoted to production.

The following prompt template is designed to be copied directly into your application or testing harness. It accepts a formal workflow definition and returns a structured deadlock analysis. The template uses square-bracket placeholders that you must replace with your specific workflow content, output schema requirements, and any additional constraints before sending it to the model. Do not ship this template with unresolved placeholders in production—your harness should validate that all required fields are populated before the API call.

textCopy
Analyze the following workflow definition for deadlocks. A deadlock is a condition where two or more steps are waiting for each other to release a resource or complete, creating a cycle that prevents any of them from proceeding.

Check for:
- Resource-wait cycles: steps holding resources while waiting for resources held by other steps
- Mutex conflicts: steps competing for exclusive access to the same resource
- Ordering deadlocks: steps that cannot proceed because their prerequisites form a cycle

[WORKFLOW_DEFINITION]

Classify the severity of each finding as 'BLOCKER', 'WARNING', or 'INFO' using these criteria:
- BLOCKER: A confirmed cycle that will prevent workflow completion under all execution paths
- WARNING: A potential deadlock that depends on runtime conditions or resource availability
- INFO: A structural concern that does not currently form a cycle but could become one after changes

For each finding, provide:
1. The severity classification
2. The specific steps or resources involved in the cycle
3. A clear description of the wait chain
4. A resolution recommendation

[OUTPUT_SCHEMA]

[CONSTRAINTS]

If no deadlocks are found, state that explicitly and explain why the workflow is deadlock-free.

To adapt this template for your system, replace [WORKFLOW_DEFINITION] with the actual YAML, JSON, or DSL representation of your workflow. The [OUTPUT_SCHEMA] placeholder should contain your expected JSON structure—for example, an array of finding objects with fields for severity, cycle_path, description, and recommendation. The [CONSTRAINTS] placeholder is where you add domain-specific rules, such as maximum resource counts, known mutex groups, or assumptions about your execution environment's concurrency model. If your workflow engine has known limitations—like a maximum number of parallel steps or specific resource types that cannot be shared—include those here to prevent false positives.

Before deploying this prompt, build a validation layer that checks the model's output against your [OUTPUT_SCHEMA]. A malformed severity field or a missing cycle_path on a BLOCKER finding should trigger a retry or fallback. For high-risk workflows where a missed deadlock could cause production outages, route all BLOCKER findings to a human reviewer before accepting automated resolution recommendations. The model can identify the cycle, but the decision to restructure dependencies or change resource allocation should remain a human judgment call when the workflow is customer-facing or revenue-critical.

The deadlock detection prompt is designed to operate as a synchronous validation step inside a larger workflow pipeline. You send a formal workflow definition (YAML, JSON, or DSL) as the [WORKFLOW_DEFINITION] input and receive a structured analysis containing detected cycles, severity classifications, and resolution guidance. This prompt should be called before any workflow is deployed, registered, or executed—not as a runtime monitor. The typical integration point is a CI/CD check, a workflow editor's pre-save hook, or a workflow engine's registration API validator. Because the output includes severity labels (BLOCKING, WARNING, INFO), your harness can make automated decisions: block deployment on BLOCKING findings, surface WARNING findings for review, and log INFO findings without interrupting the pipeline.

Validation and retry logic is critical because the model can produce malformed JSON, omit required fields, or generate cycle paths that don't match the input graph. Your harness must: (1) validate that the response is parseable JSON matching the [OUTPUT_SCHEMA]; (2) verify that every reported cycle path references nodes and edges that actually exist in the submitted workflow definition; (3) confirm that severity is one of the allowed enum values; and (4) check that resolution_guidance is present for every BLOCKING or WARNING finding. If validation fails, retry once with the same prompt plus the validation error message appended as context. If the second attempt also fails, escalate to a human reviewer with the raw model output and validation errors. For high-stakes production workflows (deployment pipelines, financial transaction systems, healthcare orchestration), require human approval on all BLOCKING findings regardless of model confidence.

Model choice and tool integration depend on your latency and accuracy requirements. For CI/CD pipelines where latency matters, use a fast model (GPT-4o, Claude 3.5 Sonnet) with temperature=0 and a strict JSON mode or structured output API. For offline batch analysis of large workflow repositories, you can use a slower but more thorough model and run multiple passes. The prompt does not require external tools or retrieval—it operates purely on the provided workflow definition. However, if your workflow definitions reference external resources (databases, APIs, queues) by name, consider providing a [RESOURCE_CATALOG] as additional context so the model can identify resource-wait cycles that span workflow steps and external system state. Log every invocation: input hash, model version, raw output, validation result, and reviewer decision. This audit trail is essential when a deadlock slips through and you need to improve the prompt or add a new detection pattern.

Next steps after integration: Start by running the prompt against your existing workflow library to establish a baseline—you'll likely find deadlocks that were previously undetected. Use those findings to tune the [CONSTRAINTS] section of the prompt, adding domain-specific deadlock patterns (e.g., 'two steps must never hold mutexes A and B in reverse order'). Build a regression test suite from confirmed deadlocks and confirmed false positives, and run it on every prompt change. If you observe the model missing deadlocks that involve external resource contention (database locks, API rate limits, queue capacity), supplement this prompt with a Resource Contention Prediction Prompt from the same playbook series rather than overloading this single prompt.