Reflection Prompt for Code Smell Identification

This prompt is designed for a static analysis agent that has already completed a first-pass scan of a codebase and produced a list of detected code smells. The reflection step acts as a second-pass reviewer: it re-examines each finding against the source code, filters false positives, adjusts severity, and prioritizes the remaining issues by impact and remediation effort. The primary job-to-be-done is to reduce noise and increase the actionability of an initial findings list before it reaches a developer's queue. The ideal user is an engineering lead or platform engineer integrating this into a CI/CD pipeline where a single-pass detector is known to produce noisy results, where the cost of a false positive is high (wasted developer time, alert fatigue), or where an auditable rationale for why a finding was escalated or suppressed is required for compliance.

This prompt is not a primary detector. It assumes an initial findings list already exists in a structured format, such as a JSON array of objects with fields for id, file_path, line_range, smell_type, initial_severity, and description. The prompt also requires access to the source code files referenced in the findings. Without this context, the reflection step cannot validate claims against the actual code and will either hallucinate justifications or rubber-stamp the initial results. The output should be a filtered and re-prioritized list with an added reflection_rationale field for each finding, explaining why it was kept, removed, or reclassified. This rationale is the auditable artifact that turns a black-box detection into a reviewable decision.

Do not use this prompt when the initial detector already has high precision and the cost of a false negative (missing a real issue) outweighs the cost of a false positive. In safety-critical systems, a reflection step that suppresses a true finding is a liability. In those cases, route all findings to a human reviewer instead of filtering programmatically. Also avoid this prompt when the codebase is too large to fit in a single context window; you will need to batch findings by module and run the reflection step per batch, with a final deduplication pass. Finally, do not use this prompt as a replacement for a proper static analysis tool—it is a filter and prioritization layer, not a detector.

This template is designed to be the core instruction set for a reflection agent. Its job is to take an initial list of detected code smells and critically re-evaluate each one. The model must act as a skeptical senior engineer, not a rubber stamp. It should demand evidence, consider context, and be willing to downgrade or dismiss findings that don't hold up under scrutiny. The output is a refined, prioritized list that a developer can trust and act on immediately.

textCopy
You are a principal software engineer performing a rigorous second-pass review of an automated code smell analysis. Your goal is to filter false positives, confirm true positives with precise reasoning, and prioritize findings by their impact on maintainability, performance, and correctness.

## INPUT
- **Initial Smell Report:** A list of detected code smells, each with a file path, line range, smell type, and a brief auto-generated description.
  ```json
  [INITIAL_SMELL_REPORT]

• Source Code: The full source code for each file mentioned in the report.

  textCopy
  [SOURCE_CODE]

• Project Context: A high-level description of the project's domain, performance requirements, and known constraints.

  textCopy
  [PROJECT_CONTEXT]

TASK

For each finding in the Initial Smell Report, perform a critical review and output a final verdict. Follow this process for each smell:

1. Evidence Check: Re-read the indicated source code. Does the code literally match the pattern described by the smell type? Quote the exact lines that are problematic.
2. Contextualization: Is this pattern actually a problem given the [PROJECT_CONTEXT]? For example, a performance smell might be acceptable in a low-traffic background job. A long method might be the clearest way to express a simple, linear workflow.
3. Impact Assessment: If the smell is a true positive, assess its real-world impact. Is it a critical bug waiting to happen, a major maintainability headache, or a minor style violation? Justify your assessment.
4. Remediation Guidance: For confirmed smells, provide a concise, actionable suggestion for how to fix it. If the fix introduces new risks, mention them.

OUTPUT SCHEMA

Return a single JSON object with a reviews array. Each element must conform to this schema:

jsonCopy
{
  "reviews": [
    {
      "original_finding_id": "string",
      "verdict": "CONFIRMED" | "FALSE_POSITIVE" | "DOWNGRADED",
      "confidence": "HIGH" | "MEDIUM" | "LOW",
      "reasoning": "A detailed explanation of your review, referencing specific code lines and project context.",
      "impact": "CRITICAL" | "MAJOR" | "MINOR" | "NONE",
      "actionable_suggestion": "A concise fix recommendation, or null if verdict is FALSE_POSITIVE."
    }
  ],
  "summary": {
    "total_reviewed": "integer",
    "confirmed": "integer",
    "false_positives": "integer",
    "downgraded": "integer",
    "top_priority_action": "The single most important fix to make, based on the highest-impact confirmed smell."
  }
}

CONSTRAINTS

• Do not hallucinate. If the source code does not contain the reported pattern, the verdict must be FALSE_POSITIVE.
• Be skeptical. The default stance is to doubt the initial report until you see clear evidence.
• Prioritize ruthlessly. Not all true positives are worth fixing now. Use the impact field to guide developer attention.
• Actionable suggestions only. Avoid vague advice like "refactor this." Be specific.

To adapt this template, replace the placeholders with data from your application layer. The [INITIAL_SMELL_REPORT] should be a JSON array of objects from your static analysis tool. The [SOURCE_CODE] block must contain the complete file content for every file referenced in the report; this is critical for the evidence check step. The [PROJECT_CONTEXT] is a free-text field that can be populated from a README, a project wiki, or a configuration file. Before deploying, validate that the model's output strictly conforms to the OUTPUT_SCHEMA. A common failure mode is the model adding extra commentary outside the JSON block, so implement a post-processing validation step that parses the JSON and checks for all required fields. If the validation fails, retry the prompt once with a stronger instruction to output only the specified JSON object.

The reflection prompt is not a standalone script; it is a second-pass filter inside a larger static analysis pipeline. The typical harness runs an initial detection prompt against a codebase or diff, collects the raw findings, and then feeds those findings into the reflection prompt along with the original source code. The reflection output should be treated as the final, curated result set—not an optional add-on. Architecturally, this means the reflection step is a synchronous gate: the pipeline does not emit results to the developer or to the review queue until reflection completes and passes validation.

Wire the reflection prompt as a dedicated step with its own retry budget and output validator. After the initial smell detection produces a JSON array of findings, construct the reflection call with [INITIAL_FINDINGS] set to that array and [SOURCE_CODE] set to the same code context used in the first pass. The model must return a structured JSON object containing reviewed_findings (the filtered and re-ranked list), false_positives_removed (with reasons), and confidence_scores. Validate the output strictly: confirm that every removed finding has a non-empty removal_reason, that confidence_scores are numeric and in range, and that no finding references a line number outside the provided source. If validation fails, retry once with the validation error injected into [PREVIOUS_ERRORS]. If the second attempt also fails, route the raw initial findings to a human review queue with a flag indicating reflection failure—never silently fall back to unfiltered output in high-risk codebases.

Model choice matters here. The reflection step benefits from a model with strong instruction-following and structured output discipline. For most teams, a capable frontier model (e.g., GPT-4o, Claude 3.5 Sonnet) works well, but if you are processing large diffs, watch the context window. Chunk the source code by file or function and run reflection per chunk, then merge results. Log every reflection call with the input findings, output findings, validation status, and any retry attempts. This trace is essential for debugging false negatives (real smells that reflection incorrectly removed) and for tuning the reflection prompt's removal criteria over time. If the pipeline operates on production code with deployment gates, require a human sign-off on any finding above a configurable severity threshold, even after reflection has confirmed it.