PR Diff Complexity Scoring Prompt

This prompt is designed for engineering managers and tech leads who need a consistent, data-driven way to assess the review burden of incoming pull requests before assigning them to a developer. Instead of relying on gut feel or a quick glance at the line count, you feed a raw git diff into the prompt and receive a structured complexity score. The score is built from four weighted dimensions: the sheer volume of the change (lines added, modified, deleted), the breadth of the change (number of files touched), the estimated impact on cyclomatic complexity (new branches, loops, or deeply nested logic), and the degree of cross-module coupling (changes that span service boundaries, shared libraries, or database schemas). The output is a decision-support artifact that helps you prioritize which PRs need a senior reviewer, which can be safely handled by a junior developer, and which should be broken into smaller, more reviewable units.

The ideal integration point is your CI/CD pipeline or a code review assignment tool. When a PR is opened, your automation extracts the diff and sends it to this prompt. The resulting JSON payload—containing a numeric score, a categorical label (e.g., low, medium, high, critical), and a breakdown of contributing factors—can be written as a comment on the PR, used to route the review to the appropriate team member, or logged for retrospective analysis of your team's review load. A concrete implementation would parse the diff with a script, pass it as the [RAW_DIFF] placeholder, and validate the output against a strict JSON schema before acting on it. If the model returns a score above a configurable threshold, the harness can automatically flag the PR for a two-person review or block merging until a designated senior engineer approves.

This prompt does not replace human judgment for critical paths, security-sensitive changes, or architectural decisions. It is a triage tool, not an approval gate. Do not use it as the sole determinant for merging or rejecting code. The complexity score is a lagging indicator of review effort, not a leading indicator of code quality or correctness. For changes touching authentication, payment processing, or data migrations, always require human review regardless of the score. If the diff is too large for a single model context window, you must chunk it and aggregate the scores, which introduces its own risks of underestimation. Start by using this prompt on non-critical repositories and calibrate the thresholds against your team's actual review time data before expanding its scope.

This template is the core instruction set for the PR Diff Complexity Scoring Prompt. It is designed to be copied directly into your application's prompt management system, LLM playground, or orchestration layer. The prompt instructs the model to analyze a provided diff and return a structured complexity score based on multiple weighted dimensions. Every variable that changes between runs is represented as a square-bracket placeholder, such as [PR_DIFF], [REPO_CONTEXT], and [RISK_THRESHOLD]. Replace these placeholders with real data at runtime before sending the request to the model.

textCopy
You are a code review complexity analyst. Your task is to analyze the provided pull request diff and produce a structured complexity score. Use the following dimensions, each scored from 1 (lowest) to 5 (highest), with a brief justification for the score.

## Scoring Dimensions
1. **Change Volume (lines_changed_score):** Based on total lines added, modified, and deleted.
2. **File Count (file_count_score):** Based on the number of distinct files touched.
3. **Cyclomatic Complexity Impact (cyclomatic_complexity_score):** Assess new or modified control flow structures (loops, conditionals, branches).
4. **Cross-Module Coupling (coupling_score):** Assess changes that span multiple modules, packages, or services, especially when they modify shared interfaces or data models.

## Inputs
- **Diff:** [PR_DIFF]
- **Repository Context (optional):** [REPO_CONTEXT]

## Output Schema
Return ONLY a valid JSON object with no additional text or markdown fences. The object must conform to this structure:
{
  "overall_complexity_score": <float between 1.0 and 5.0>,
  "complexity_level": "low" | "medium" | "high" | "critical",
  "dimension_scores": {
    "lines_changed_score": <integer 1-5>,
    "file_count_score": <integer 1-5>,
    "cyclomatic_complexity_score": <integer 1-5>,
    "coupling_score": <integer 1-5>
  },
  "score_justifications": {
    "lines_changed": "<brief explanation>",
    "file_count": "<brief explanation>",
    "cyclomatic_complexity": "<brief explanation>",
    "coupling": "<brief explanation>"
  },
  "review_recommendation": "<one-sentence guidance on review priority and suggested reviewer seniority>"
}

## Constraints
- [CONSTRAINTS]
- If the diff is empty or cannot be parsed, return a JSON object with an `error` field describing the issue.
- If the repository context is provided, use it to improve the accuracy of the coupling and cyclomatic complexity assessments.

## Risk Threshold
- Flag any dimension with a score of 4 or higher as a potential review bottleneck.
- If the overall complexity score is above [RISK_THRESHOLD], the `complexity_level` must be "high" or "critical".

To adapt this template, start by replacing [PR_DIFF] with the actual unified diff text from your version control system. The [REPO_CONTEXT] placeholder can be populated with a summary of the repository's architecture, key module boundaries, or a directory tree to improve the model's understanding of coupling. The [CONSTRAINTS] placeholder allows you to inject organization-specific rules, such as 'ignore changes to markdown files' or 'treat any change to the /auth module as high coupling.' Finally, set [RISK_THRESHOLD] to a float like 3.5 to control when a PR is automatically flagged as high complexity. After substitution, the prompt is ready for a single-turn request to a capable LLM. Always validate the output JSON against the expected schema before acting on the score.

The PR Diff Complexity Scoring Prompt is designed to be called programmatically within a CI/CD pipeline, a code review automation service, or a developer CLI tool. The primary integration point is immediately after a pull request is opened or updated. The application layer must fetch the raw diff (e.g., via git diff or the GitHub/GitLab API), inject it into the [DIFF] placeholder, and parse the structured JSON output. Because the output drives reviewer assignment and merge gating, the harness must validate the response schema before acting on the score. Do not use this prompt to block merges autonomously without a human-readable summary and an override mechanism.

The implementation should follow a strict validate-retry-escalate pattern. First, define a JSON schema for the expected output: a root object with required integer fields lines_changed, files_changed, complexity_score (1-10), and cross_module_coupling (1-5), plus a rationale string and a risk_factors array of strings. After receiving the model response, validate it against this schema. If validation fails, retry once with the same prompt but append the validation error to the [CONSTRAINTS] section: 'Your previous output failed JSON schema validation with the following errors: [ERROR_DETAILS]. You must output strictly valid JSON matching the schema.' If the second attempt also fails, log the failure, set a default high-complexity score (e.g., 8), and flag the PR for mandatory human review. For model choice, a fast, cost-effective model like GPT-4o-mini or Claude 3.5 Haiku is sufficient for most diffs. For very large diffs (>1000 lines), truncate to the first 1000 lines and append a note in [CONTEXT] that the diff was truncated, or switch to a model with a larger context window like Gemini 1.5 Pro.

Logging and observability are critical for tuning the scoring threshold over time. Log the raw complexity score, the PR ID, the number of files changed, the model used, and the latency for every call. Track the correlation between high complexity scores and actual review outcomes (e.g., review time, bugs found post-merge) to calibrate your scoring thresholds. Avoid wiring the score directly to a merge block without a grace period. Start by using the score to add a label (e.g., complexity:high) and recommend a senior reviewer. Only after validating the scoring against your team's historical data should you consider gating merges on a maximum complexity threshold.