PR Diff Test Coverage Gap Analysis Prompt

This prompt is designed for QA automation engineers and platform teams who need a structured, automated signal about test coverage gaps before a pull request merges. The core job-to-be-done is preventing regressions by surfacing what isn't tested. The ideal user is integrating this into a CI/CD pipeline as a merge gate, using it during manual code review to quickly identify coverage blind spots, or running it as part of a pre-release QA checklist. It assumes you can provide the full code diff, the relevant test files, and optionally a coverage report. It does not execute tests, judge the quality of existing tests, or replace human judgment for critical security and business logic paths.

To use this prompt effectively, you must supply three concrete inputs: the [DIFF] of the pull request, the [TEST_SUITE] files that cover the modified areas, and an optional [COVERAGE_REPORT] for additional signal. The prompt works by mapping each changed function, modified branch, and new code path in the diff to the corresponding test cases. It then identifies gaps where a code path has no matching test. The output is a structured gap report with file paths, line ranges, risk scores, and recommended test types. This is not a general-purpose code review prompt; it is specifically for coverage gap analysis. Do not use it for style review, performance analysis, or security auditing unless those are secondary signals in the gap report.

There are clear boundaries for when this prompt should not be used. If the diff is for a configuration change, documentation update, or dependency bump with no code logic changes, the analysis will produce noise. If the test suite is sparse or poorly organized, the gap report will be overwhelmingly large and may not be actionable. In high-risk domains such as authentication, authorization, or financial transaction logic, the prompt's output must be treated as advisory and require mandatory human review. The prompt identifies what is missing; your team decides what to write and what risk to accept. For a complete pre-merge workflow, pair this prompt with the Pre-Merge Test Gap Summary Prompt to synthesize multiple signals into a go/no-go recommendation.

The following prompt template is designed to be copied directly into your AI system. It instructs the model to adopt the persona of a QA automation engineer and perform a rigorous, structured analysis of a code diff against an existing test suite. The prompt enforces a strict output schema, requires evidence for every finding, and demands a risk score for each gap. Before using this template, you must replace every square-bracket placeholder with the actual data for your specific pull request and test suite. The prompt is self-contained and can be used independently of the rest of this playbook, though the surrounding sections on validation, failure modes, and evaluation criteria are critical for production use.

textCopy
You are a senior QA automation engineer. Your task is to perform a structured test coverage gap analysis on a pull request diff.

## INPUT
- CODE_DIFF:

[CODE_DIFF]

codeCopy
- EXISTING_TEST_SUITE:

[EXISTING_TEST_SUITE]

codeCopy
- COVERAGE_REPORT (optional):

[COVERAGE_REPORT]

codeCopy

## CONSTRAINTS
- Every flagged gap MUST map to a specific hunk in the CODE_DIFF.
- Every flagged gap MUST include a coverage rationale explaining why existing tests do not cover the change.
- Do not flag code that is unreachable, generated, or configuration-only unless it introduces a new execution path.
- If the COVERAGE_REPORT is provided, use it to confirm coverage status. If not provided, infer coverage gaps from the EXISTING_TEST_SUITE alone and note the lower confidence.
- Do not recommend tests for code that is purely cosmetic (whitespace, comments, formatting).

## OUTPUT_SCHEMA
Return a single JSON object with the following structure:
{
  "analysis_summary": {
    "total_files_changed": <integer>,
    "total_hunks": <integer>,
    "gaps_found": <integer>,
    "critical_gaps": <integer>,
    "high_gaps": <integer>,
    "medium_gaps": <integer>,
    "low_gaps": <integer>
  },
  "gaps": [
    {
      "gap_id": "GAP-<3-digit-integer>",
      "file_path": "<string>",
      "line_range": "<start_line>-<end_line>",
      "diff_hunk_reference": "<brief description of the change>",
      "risk_score": "critical|high|medium|low",
      "gap_type": "untested_function|modified_branch|new_code_path|exception_handler|boundary_condition|concurrency_path|other",
      "coverage_rationale": "<explanation of why existing tests do not cover this change>",
      "recommended_test_type": "unit|integration|e2e|contract|property|fuzz|manual",
      "recommended_test_description": "<concrete description of the test case, including suggested inputs and expected outcomes>",
      "existing_test_reference": "<name of closest existing test or 'none'>"
    }
  ],
  "safe_changes": [
    {
      "file_path": "<string>",
      "line_range": "<start_line>-<end_line>",
      "reason": "<why this change is adequately covered or low-risk>"
    }
  ]
}

## RISK_SCORE DEFINITIONS
- critical: Untested change in authentication, authorization, data integrity, payment, or PII handling.
- high: Untested change in core business logic, API contract, or error handling with user-facing impact.
- medium: Untested change in non-critical logic, logging, or internal helper with indirect impact.
- low: Untested change in formatting, comments, or dead code removal with no behavioral impact.

## INSTRUCTIONS
1. Parse the CODE_DIFF and identify every changed function, modified branch, new code path, exception handler, and boundary condition.
2. For each identified change, check the EXISTING_TEST_SUITE for coverage. If a COVERAGE_REPORT is provided, cross-reference it.
3. For any change without adequate coverage, populate a gap entry in the output.
4. Assign a risk_score based on the definitions above.
5. Recommend a specific, actionable test case for each gap.
6. Include a safe_changes entry for any change that is adequately covered or demonstrably low-risk.
7. Return ONLY the JSON object. No markdown fences, no commentary.

To adapt this prompt for your environment, replace [CODE_DIFF] with the unified diff output from your version control system, [EXISTING_TEST_SUITE] with the relevant test files or a summary of test coverage, and [COVERAGE_REPORT] with the output of your coverage tool if available. The OUTPUT_SCHEMA is designed to be machine-readable for downstream automation, but you can add or remove fields to match your ticketing system or CI pipeline. If your model does not reliably produce valid JSON, pair this prompt with a structured output API or a post-generation validation step as described in the implementation harness section. For high-risk repositories, always require human review of critical and high-severity gaps before merging.

This prompt is designed to run as a gated step in a CI/CD pipeline, triggered on pull request creation or update. The harness must supply the unified diff, a structured representation of the existing test suite (file paths, function names, covered line ranges), and any relevant coverage report data. The model call should be treated as a non-blocking analysis that enriches the PR with a structured gap report, not as a merge gate by itself. A human reviewer or a downstream validation system must confirm findings before blocking a merge.

The implementation should validate the model's output against the input diff before surfacing results. Every flagged gap must map to a specific diff hunk using file path and line range. The harness should reject any finding that references code outside the diff context or that duplicates an existing test case already present in the test suite input. Use a post-processing validator that cross-references the output's file_path and line_range fields against the diff hunks and the provided test coverage map. If more than 10% of findings fail this cross-reference, the entire output should be discarded and the model retried once with a stricter prompt that includes the validation failure details. Log the raw output, validation results, and retry count for observability.

For model choice, use a model with strong code reasoning capabilities and a large context window sufficient to hold the full diff plus test suite summary. If the diff exceeds the context window, chunk by file or module and run the prompt per chunk, then merge results with deduplication logic. The output schema should be enforced via structured output mode (JSON mode or function calling) to ensure the gaps array, risk_score, and recommended_test_type fields are reliably parseable. Store results as a PR comment or check run annotation, linking each finding to the relevant diff line. Never auto-block a merge based solely on this prompt's output without human review for high-risk repositories or regulated codebases.

For evaluation, maintain a golden dataset of known diffs with manually annotated test gaps. Run this prompt against the golden set on each prompt revision and measure precision (do flagged gaps correspond to real untested code?) and recall (are known gaps found?). Track false positives over time—findings that reference covered code or code outside the diff—and tune the prompt and validator thresholds accordingly. In production, monitor the rate of findings dismissed by reviewers as false positives and use that signal to trigger prompt updates or validator rule adjustments.