Structured Review Feedback Generation Prompt

This prompt is designed for engineering teams integrating automated code review into a CI/CD pipeline. Its job is to ingest a pull request diff and produce a machine-readable JSON payload of review findings. Each finding maps to a specific line, carries a severity level and category, and includes a suggested fix. The output is built for direct ingestion by code review tools, ticketing systems, or dashboards. Use this prompt when you need consistent, structured, and actionable feedback that can be processed programmatically.

The ideal user is a platform engineer or developer setting up an automated review step that runs alongside linters and tests. The prompt requires a raw unified diff as input, along with a strict JSON output schema. It works best for statically analyzable concerns—code style violations, potential null dereferences, resource leaks, and clear anti-patterns. It is not a replacement for human review on critical paths, security-sensitive changes, or architectural decisions. For those, route the output to a human approval queue rather than auto-applying findings.

Do not use this prompt for natural-language code summaries, conversational feedback, or subjective design critique. It is optimized for deterministic, schema-conformant output that downstream systems can parse without ambiguity. Before deploying, validate the JSON output against your schema in a staging pipeline, and run a regression suite of known diffs to measure finding accuracy and false positive rates. If the prompt misses a finding class you care about, add a [CONSTRAINTS] block with explicit rules and counterexamples before considering fine-tuning.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a structured code reviewer, consuming a raw diff and producing a strict JSON payload that maps findings to specific lines, severity levels, and actionable fix suggestions. The output is intended for direct ingestion by code review tools, dashboards, or automated comment posters, not for free-text human reading. Before using this template, ensure you have a reliable method for extracting the full file diff and any relevant context from your repository, as the model cannot access your codebase directly.

codeCopy
SYSTEM:
You are a strict code review agent. Your only output is a valid JSON object conforming to the [OUTPUT_SCHEMA] below. Do not include any text outside the JSON object. Do not wrap the JSON in markdown fences.

USER:
Analyze the following pull request diff for bugs, logic errors, security vulnerabilities, and code quality issues.

[CONTEXT]
- Repository: [REPO_NAME]
- Base Branch: [BASE_BRANCH]
- Target Branch: [TARGET_BRANCH]
- Review Focus: [REVIEW_FOCUS]

[INPUT]
```diff
[RAW_DIFF]

[OUTPUT_SCHEMA] { "summary": "string (a concise, one-sentence summary of the change)", "findings": [ { "id": "string (unique finding identifier, e.g., FIND-001)", "file": "string (full file path)", "line_range": ["number (start line in the new file)", "number (end line in the new file)"], "category": "string (enum: 'bug', 'security', 'performance', 'maintainability', 'style')", "severity": "string (enum: 'critical', 'high', 'medium', 'low', 'info')", "title": "string (a short, descriptive title for the finding)", "description": "string (a clear explanation of the issue and why it is a problem)", "suggestion": "string (a concrete, code-level suggestion for fixing the issue)", "confidence": "number (a score from 0.0 to 1.0 indicating how certain the model is about this finding)" } ], "risk_assessment": { "overall_risk": "string (enum: 'low', 'medium', 'high', 'critical')", "breaking_change_detected": "boolean", "test_coverage_concern": "boolean" } }

[CONSTRAINTS]

• Only report findings present in the [RAW_DIFF]. Do not hallucinate issues.
• Map findings to the correct line numbers in the new version of the file.
• If no issues are found, return an empty findings array and a risk_assessment with overall_risk set to low.
• For severity, use critical only for security vulnerabilities or data loss bugs. Use high for functional bugs. Use medium for maintainability issues. Use low for style nits.
• The suggestion field must be a specific code change, not a vague recommendation.

To adapt this template, replace the square-bracket placeholders with data from your CI/CD environment. [RAW_DIFF] should be the complete unified diff of the pull request. [REVIEW_FOCUS] can be used to narrow the model's attention, for example, to 'security and authentication logic' or 'database migration safety'. The [OUTPUT_SCHEMA] is the contract your application must validate against. After receiving the model's response, always run a JSON schema validator before processing the findings. If validation fails, trigger a retry with a repair prompt that includes the raw output and the validation error message. For critical or high severity findings, route the payload to a human reviewer queue instead of automatically posting comments.

The structured review feedback prompt is designed to be a deterministic component in an automated review pipeline, not a conversational assistant. Its primary contract is to accept a raw diff and a strict JSON schema, and to return a machine-readable payload that can be directly ingested by code review platforms like GitHub, GitLab, or Gerrit. The implementation harness must treat the LLM call as a function with a well-defined input and output, wrapping it in validation, retry logic, and human approval gates before any finding is posted as a review comment.

To wire this into an application, start by constructing the [INPUT] from the actual git diff output, truncated to fit the model's context window. The [OUTPUT_SCHEMA] placeholder should be replaced with a complete JSON Schema definition that includes required fields (id, file, line, severity, category, finding, suggestion), enums for severity (critical, high, medium, low, info) and category (bug, security, performance, maintainability, style, documentation), and a maxItems constraint on the top-level array. After receiving the model's response, the harness must validate it against this schema. If validation fails, implement a single retry by feeding the raw response and the validation error back into the prompt's [CONSTRAINTS] section, instructing the model to repair the output. If the retry also fails, log the failure and alert the on-call channel; never post invalid data to the review tool.

For high-risk repositories, the harness must enforce a human approval step. All findings with a severity of critical or high should be routed to a review queue where a senior engineer can approve, edit, or dismiss each finding before it is posted. This can be implemented as a blocking step in the CI pipeline or as a draft review that requires manual publish. Additionally, implement observability by logging every prompt request, the validated response, the retry count, and the final action (posted, queued for approval, or failed). This trace data is essential for debugging prompt drift, model misbehavior, and schema evolution over time. Avoid using this prompt on diffs larger than the model's effective context window without first chunking the diff by file and running the prompt per file, then merging the results.