Channel and Select Statement Deadlock Prompt

This prompt is a static analysis tool for Go engineers and CI/CD pipelines that must detect deadlock risks in goroutine communication patterns before code merges. It is designed to analyze the structure of channel operations and select statements within a provided source file or function, identifying unbuffered channel mismatches, missing default cases that cause goroutine starvation, and select constructs where no case can proceed. The primary job-to-be-done is to produce a communication graph and a trace of potential deadlock scenarios, turning a manual, error-prone review into a structured, repeatable analysis. The ideal user is a senior Go engineer or a platform team automating pre-merge safety checks, not a developer debugging a live production incident.

To use this prompt effectively, you must provide the full source code of the functions or files containing the concurrency logic. The prompt assumes the code compiles and focuses exclusively on chan and select semantics; it will not catch lock-based deadlocks, race conditions on shared memory, or runtime goroutine leaks. The required input is a complete, self-contained code block. The expected output is a structured report that includes a list of identified communication pairs, a directed graph of channel dependencies, and a trace of events that would lead to a deadlock. You should wire this into a CI pipeline by running it on the diff of a pull request, validating that the output schema contains deadlock_detected and trace fields, and failing the check only if a high-severity deadlock is found with a complete, reproducible trace.

Do not use this prompt for analyzing runtime traces, pprof goroutine dumps, or code written in languages other than Go. It is not a substitute for the Go race detector or for stress-testing with go test -race. The prompt is a pre-merge guardrail, and its findings should be reviewed by a human for complex or novel concurrency patterns. If the analysis returns a deadlock trace, treat it as a high-priority finding that requires a code change or a documented justification for why the static analysis is a false positive. For production debugging, pair this with runtime tooling, not a static prompt.

This prompt template is designed to analyze Go source code containing channel operations and select statements for potential deadlock scenarios. It accepts raw code, optional runtime traces, and configuration parameters to produce a structured deadlock analysis. The template uses square-bracket placeholders that you replace with actual values before sending the prompt to the model. Each placeholder maps to a specific input source in your application: code snippets come from PR diffs or repository files, runtime traces come from your observability pipeline, and constraints come from your team's review policies.

textCopy
You are a concurrency safety reviewer specializing in Go channel deadlock detection.

Analyze the following Go code for deadlock risks in channel operations and select statements.

## INPUT

### Code to Review
[CODE_SNIPPET]

### Runtime Trace (optional)
[GOROUTINE_TRACE]

### Additional Context
- Package: [PACKAGE_NAME]
- Function(s) under review: [FUNCTION_NAMES]
- Known goroutine count: [GOROUTINE_COUNT]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "findings": [
    {
      "id": "string",
      "severity": "DEADLOCK | STARVATION | LEAK | WARNING",
      "location": {
        "file": "string",
        "line_start": number,
        "line_end": number
      },
      "pattern": "UNBUFFERED_CHANNEL_MISMATCH | MISSING_DEFAULT_CASE | SELECT_STARVATION | BLOCKING_SEND_NO_RECEIVER | BLOCKING_RECEIVE_NO_SENDER | CLOSED_CHANNEL_SEND | NIL_CHANNEL_OPERATION | CIRCULAR_WAIT",
      "description": "string explaining the deadlock mechanism",
      "reproduction_scenario": "string describing how to trigger the deadlock",
      "fix_suggestion": "string with concrete code change recommendation",
      "communication_graph": {
        "nodes": ["string goroutine or channel names"],
        "edges": [{"from": "string", "to": "string", "operation": "SEND | RECEIVE", "blocking": true}]
      }
    }
  ],
  "deadlock_trace": "string describing the circular wait chain if a deadlock exists",
  "overall_risk": "HIGH | MEDIUM | LOW | NONE",
  "summary": "string one-paragraph assessment"
}

## ANALYSIS RULES
1. For each select statement, check if a default case exists and whether it prevents indefinite blocking.
2. Trace every channel send to its corresponding receive and vice versa. Flag unmatched operations.
3. Identify circular dependencies where goroutine A waits on B, B waits on C, and C waits on A.
4. Check for sends on unbuffered channels without a concurrent receiver goroutine.
5. Flag goroutines that block on channel operations without a cancellation path (context.Context or done channel).
6. If a runtime trace is provided, correlate static findings with observed goroutine states.
7. Do not flag patterns protected by explicit synchronization that you can verify in the code.
8. If the code is incomplete or the analysis is uncertain, set overall_risk to the worst-case scenario and note the uncertainty in summary.

To adapt this template, replace each placeholder with concrete values from your review pipeline. For [CODE_SNIPPET], provide the complete function or file content, not just the diff, because deadlock analysis requires seeing all channel interactions in scope. For [CONSTRAINTS], specify rules like "ignore test files" or "only flag findings with severity DEADLOCK or STARVATION" to control output volume. The [GOROUTINE_TRACE] placeholder accepts the output of runtime.Stack([]byte, true) or equivalent goroutine dump data, which dramatically improves detection accuracy when available. If you don't have a trace, replace the placeholder with "No runtime trace available" and the model will rely solely on static analysis. Before deploying this prompt, validate the output against known deadlock examples from your codebase and tune the ANALYSIS RULES section if the model produces false positives for patterns your team considers safe.

This prompt is designed to be called programmatically as part of a pre-merge code review pipeline or an interactive CLI tool for Go developers. The primary integration point is a diff ingestion service that extracts only Go source files containing chan, select, go func, or sync primitives, packages them with a lightweight static analysis summary, and sends the assembled [CONTEXT] to the model. Because deadlock analysis is computationally expensive for LLMs on large codebases, you should pre-filter diffs to include only the changed functions plus any directly called functions (call graph depth of 1) to stay within context windows and manage latency. The model should receive the code, a list of channel declarations with their buffer sizes and directions, and any existing go vet or staticcheck findings related to concurrency.

Validation and output parsing: The prompt instructs the model to return a JSON array of deadlock findings. Your harness must validate this output against a strict schema before accepting it. Each finding object requires severity (one of CRITICAL, HIGH, MEDIUM, LOW), file_path, line_range, deadlock_type (one of unbuffered_channel_mismatch, select_starvation, missing_default_case, goroutine_leak, circular_wait), description, and fix_suggestion. Use a JSON Schema validator in your pipeline to reject malformed responses and trigger a retry. For retries, append the validation error message to the next request as [PREVIOUS_VALIDATION_ERROR] so the model can self-correct. Set a maximum of 2 retries before falling back to a human review flag. Model choice: Use a model with strong code reasoning capabilities (e.g., Claude 3.5 Sonnet, GPT-4o) and set temperature=0.1 for deterministic output. For cost-sensitive pipelines, route MEDIUM and LOW severity findings to a smaller model for initial triage and escalate only CRITICAL and HIGH to the primary model.

Logging and observability: Log every invocation with the commit SHA, file paths analyzed, number of findings returned, retry count, and model latency. Store the raw model response and the validated output in your review database for auditability. If the model returns a deadlock_graph field (a Mermaid.js diagram of channel dependencies), render it in your review UI but do not block the pipeline on its presence—it is a supplementary artifact. Human review integration: Findings with severity: CRITICAL should block merge and require a human reviewer to acknowledge or dismiss each finding. Findings with severity: HIGH should generate a non-blocking comment on the PR with the fix_suggestion included. MEDIUM and LOW findings can be aggregated into a summary comment. What to avoid: Do not run this prompt on every commit unconditionally—use file extension and keyword filters to trigger it only when concurrency-relevant code changes. Do not trust the model's line numbers without verifying them against the current diff; line numbers can drift if the model references the full file rather than the diff hunk. Always include a [CONSTRAINTS] block that reminds the model to only report findings with high confidence and to explicitly state when no deadlock risks are detected rather than returning an empty array silently.