Pull Request Smell Summary Prompt

This prompt is designed for CI/CD pipelines and platform engineering teams that need to generate a reviewer-friendly summary of code smells from a full pull request diff. It takes the raw diff as input and produces a structured summary grouped by smell category, a risk heatmap, the top three action items, and a go/no-go recommendation suitable for automated merge gates. The primary job-to-be-done is triage and decision support, not detailed code review. Use this prompt when you need a single, scannable output that distills multiple smell detectors into a decision-ready format for a release manager or on-call engineer who needs to decide whether a PR should proceed, pause, or escalate.

The ideal user is a platform engineer embedding this prompt into an automated merge queue or a tech lead reviewing a daily digest of high-risk PRs. The prompt assumes that detailed smell detection has already occurred—either via upstream static analysis tools, separate detection prompts, or that the model is capable of performing that detection within the same call. You must provide the full PR diff as [INPUT] and, optionally, a [CONTEXT] block containing team-specific severity thresholds, known false positive patterns, or domain-specific anti-pattern catalogs. The output schema should be specified in [OUTPUT_SCHEMA] to enforce a consistent JSON structure with fields for smell_summary, risk_heatmap, top_action_items, and go_no_go_recommendation. Without a strict output schema, the model may produce narrative prose that is difficult to parse in an automated pipeline.

Do not use this prompt for line-by-line code review, for generating fix suggestions, or as a replacement for detailed analysis. It is a summarization and triage layer, not a diagnostic tool. If you need specific file-and-line mappings with remediation guidance, use the sibling prompt 'PR Diff Code Smell Detection Prompt Template' instead. Do not use this prompt when the diff is too large for a single context window—chunk the diff by file or module and run detection prompts first, then feed the aggregated findings into this summary prompt. For high-risk domains such as security vulnerabilities or data integrity changes, always require human review of the go/no-go recommendation before merging. The prompt is a decision aid, not a decision maker.

This prompt template is designed to be dropped directly into your CI/CD pipeline or code review automation. It takes a raw pull request diff as input and produces a structured JSON summary that your merge gates, review dashboards, or notification systems can consume. The template enforces a strict output schema so downstream tooling can rely on consistent field names, types, and structure—no parsing guesswork required. Before copying, review the placeholders in square brackets and replace them with your team's specific constraints, severity definitions, and risk thresholds.

textCopy
You are a senior code reviewer analyzing a pull request diff for code smells, anti-patterns, and maintainability risks.

## INPUT
[PR_DIFF]

## CONTEXT
- Repository: [REPO_NAME]
- Base branch: [BASE_BRANCH]
- Target branch: [TARGET_BRANCH]
- Team standards: [TEAM_STANDARDS_REFERENCE]
- Files changed: [FILE_LIST]

## CONSTRAINTS
- Only report findings you can map to specific file paths and line ranges in the diff.
- Do not flag style issues already covered by the team's linter configuration.
- If the diff is empty or contains no detectable smells, return an empty findings array with a 'go' recommendation.
- Severity levels: 'critical' (merge blocker), 'high' (must fix before deploy), 'medium' (should fix in this PR), 'low' (note for future cleanup).
- For each finding, include a confidence score from 0.0 to 1.0. Findings below [MIN_CONFIDENCE_THRESHOLD] should be omitted.
- Group findings by category using the categories defined in [CATEGORY_TAXONOMY].

## OUTPUT SCHEMA
Return valid JSON matching this structure exactly:
{
  "summary": {
    "total_findings": <integer>,
    "categories_affected": [<string>],
    "risk_heatmap": {
      "critical": <integer>,
      "high": <integer>,
      "medium": <integer>,
      "low": <integer>
    },
    "top_action_items": [
      {
        "rank": <integer>,
        "finding_id": <string>,
        "rationale": <string>
      }
    ],
    "merge_recommendation": "go" | "no-go" | "conditional-go",
    "recommendation_reason": <string>
  },
  "findings": [
    {
      "id": <string>,
      "category": <string>,
      "severity": "critical" | "high" | "medium" | "low",
      "confidence": <float>,
      "file": <string>,
      "line_range": {
        "start": <integer>,
        "end": <integer>
      },
      "title": <string>,
      "description": <string>,
      "suggestion": <string>,
      "references": [<string>]
    }
  ],
  "diff_metadata": {
    "files_analyzed": <integer>,
    "lines_added": <integer>,
    "lines_removed": <integer>,
    "analysis_timestamp": <string>
  }
}

## INSTRUCTIONS
1. Parse the diff to identify all changed files and line ranges.
2. For each changed file, scan for code smells and anti-patterns defined in [CATEGORY_TAXONOMY].
3. Assign severity based on [SEVERITY_RUBRIC].
4. Group findings by category.
5. Build the risk heatmap by counting findings per severity level.
6. Select the top 3 action items by severity (highest first), then by confidence (highest first).
7. Determine the merge recommendation:
   - 'no-go' if any critical finding exists.
   - 'conditional-go' if high-severity findings exist but have clear, low-risk fix paths.
   - 'go' otherwise.
8. Return the complete JSON object following the output schema exactly.

To adapt this template for your team, start by defining your [CATEGORY_TAXONOMY]—the specific smell categories you care about, such as error handling, concurrency, security, naming, duplication, or test quality. Replace [SEVERITY_RUBRIC] with your team's agreed-upon definitions for each severity level, including examples of what qualifies as critical versus low. Set [MIN_CONFIDENCE_THRESHOLD] to filter out low-confidence noise; 0.6 is a reasonable starting point for most teams. The [TEAM_STANDARDS_REFERENCE] placeholder should point to your style guide, architectural decision records, or coding conventions document so the model can distinguish intentional patterns from actual smells. If your CI system already provides file lists and branch metadata, wire those into [FILE_LIST], [BASE_BRANCH], and [TARGET_BRANCH] automatically rather than asking the model to extract them from the diff.

Before deploying this prompt into an automated merge gate, test it against a golden dataset of known PRs with labeled smells. Validate that the JSON output parses correctly, that finding IDs are unique and stable across runs, and that the merge recommendation aligns with your team's manual review decisions. Pay special attention to false positives on intentional patterns—if your team commonly uses a pattern that the model flags as a smell, add an explicit exclusion to the [CONSTRAINTS] section. For high-risk repositories, keep a human-in-the-loop step: use 'conditional-go' as a signal to request manual review rather than blocking the merge outright. The next section covers how to wire this template into an application harness with validation, retries, and logging.

The Pull Request Smell Summary Prompt is designed to be called as a single step in an automated pipeline, not as a conversational chat. The primary integration point is a CI/CD workflow (GitHub Actions, GitLab CI, Jenkins) that triggers on pull request creation or update. The application layer is responsible for gathering the full PR diff, assembling the prompt with the correct placeholders, calling the model, validating the structured output, and posting the summary as a review comment or status check. Do not expose this prompt directly to end users; the diff input is large, the output schema is strict, and the risk of hallucinated findings requires automated validation before the summary reaches a human reviewer.

Integration flow: 1) The CI job fetches the PR diff using the provider's API (e.g., git diff origin/main...HEAD). 2) The diff is truncated to a maximum token budget (reserve ~60% of the model's context window for the diff, leaving room for the system prompt and output). If the diff exceeds the budget, split by file and run multiple passes, then merge and deduplicate findings. 3) The prompt template is populated with [PR_DIFF], [REPOSITORY_CONTEXT] (language, framework, team conventions), and [SEVERITY_RUBRIC] (team-specific definitions of Critical, High, Medium, Low). 4) The model is called with response_format set to JSON schema mode (OpenAI) or with a structured output constraint (Anthropic, Gemini). 5) The raw JSON output is validated against the expected schema: required fields (summary, categories, heatmap, top_actions, go_no_go), enum values for severity and category types, and line-range references that fall within the diff boundaries. 6) If validation fails, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the retry also fails, fail the check open (post a warning, not a block) and log the raw output for manual review.

Model selection: Use a model with strong structured output adherence and a context window large enough for typical PR diffs. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro are good defaults. For cost-sensitive pipelines, a smaller model (GPT-4o-mini, Claude 3 Haiku) can work if you tighten the output schema and increase validation strictness. Avoid models known to drift on long-context structured generation without explicit JSON mode. Logging and observability: Log the prompt version, model, diff size in tokens, validation pass/fail, retry count, and the final structured output. Attach the smell summary to the PR as a comment or status check with a link to the raw log. This creates an audit trail for false positive disputes and prompt drift detection over time. Human review gate: The go_no_go recommendation is advisory only. For repositories with compliance requirements (SOC 2, HIPAA, PCI), configure the CI check to post a non-blocking summary and require a human reviewer to acknowledge Critical or High findings before merge. Never auto-merge on a go signal alone without human approval for regulated codebases.

Eval and calibration: Before enabling the prompt in production, run it against a golden dataset of 20-30 PRs with known smell findings (both true positives and intentional clean diffs). Measure precision (do flagged smells match known issues?), recall (are known smells missed?), and hallucination rate (are findings referencing lines that don't exist in the diff?). Calibrate the severity rubric by comparing model-assigned severities against team-assigned severities on the golden set. Re-run this eval suite on any prompt version change and set a regression threshold (e.g., recall must not drop below 85% on known Critical smells). Store eval results alongside prompt versions in your prompt registry. Failure modes to monitor: The most common production failure is the model inventing file paths or line numbers that don't exist in the actual diff—always validate line ranges against the diff. The second is category misclassification (e.g., flagging a naming issue as a security smell). The third is severity inflation on large diffs, where the model over-flags to appear thorough. Mitigate these with strict output validation, category-enum constraints, and periodic human spot-checks on a sample of production summaries.