Code Smell Severity Triage Prompt

This prompt is for tech leads, platform engineers, and senior developers who receive a high volume of findings from multiple static analysis tools, linters, and AI code reviewers. The core job-to-be-done is turning an unstructured, noisy, and often duplicative list of detected code smells into a single, severity-ranked, and deduplicated triage report that a team can act on immediately. The ideal user is someone who owns code quality for a repository or service and needs to decide what must be fixed before merge, what can be deferred to a backlog, and what is likely a false positive that should be suppressed. Required context includes the raw list of findings from one or more detectors, the relevant code snippets or file paths, and a team-defined severity rubric that calibrates what 'critical,' 'high,' 'medium,' and 'low' mean in their specific codebase.

Do not use this prompt when you have only one detector's output with fewer than five findings—a simpler deduplication or direct review is more efficient. Do not use it for real-time security vulnerability triage where exploitability requires immediate human security engineer judgment; this prompt prioritizes maintainability and code health risks, not active threat response. Avoid using it when the team has no agreed-upon severity rubric, as the model will default to generic heuristics that may not match your risk tolerance. The prompt is designed for batch triage of 10–200 findings; for larger volumes, split the input into logical groups by component or detector to stay within context windows and maintain ranking quality.

Before using this prompt, ensure you have a calibrated severity rubric documented and included in the [RUBRIC] placeholder. Without it, the model will make reasonable but potentially misaligned severity calls. After receiving the triage report, always spot-check the top 3 critical findings and a random sample of false-positive flags against your own judgment. This prompt reduces triage time, not replaces engineering judgment. If your team lacks a rubric, run the prompt once with a generic severity scale, review the output with the team, and use that calibration session to define your own thresholds before integrating this into an automated CI pipeline.

This prompt template is designed to take a raw list of code smells from one or more detection tools and produce a severity-ranked, deduplicated triage report. It is built for tech leads and platform teams who need to turn a noisy stream of findings into a clear, actionable queue. The template uses square-bracket placeholders for all variable inputs, making it safe to drop into a prompt management system, a CI/CD pipeline, or an internal review tool. Before using it, ensure you have defined your team's severity rubric and have a representative set of examples to calibrate the model's judgment against your own standards.

textCopy
You are a senior software engineer and code review lead responsible for triaging code smell findings.

Your task is to analyze a list of detected code smells and produce a severity-ranked, deduplicated triage report.

## INPUT

[FINDINGS_LIST]

## CONTEXT

- Repository: [REPO_NAME]
- Branch/PR: [BRANCH_OR_PR_ID]
- Team Severity Rubric: [SEVERITY_RUBRIC]
- Known False Positive Patterns: [FALSE_POSITIVE_PATTERNS]
- Deferral Candidates (low-risk patterns to suppress): [DEFERRAL_PATTERNS]

## OUTPUT SCHEMA

Return a JSON object with the following structure:
{
  "report_id": "string",
  "generated_at": "ISO8601 timestamp",
  "summary": {
    "total_findings": "number",
    "after_dedup": "number",
    "critical": "number",
    "high": "number",
    "medium": "number",
    "low": "number",
    "false_positives_flagged": "number",
    "deferred": "number"
  },
  "findings": [
    {
      "id": "string",
      "original_ids": ["string"],
      "category": "string",
      "file": "string",
      "line_range": "start-end",
      "description": "string",
      "severity": "critical|high|medium|low",
      "rationale": "string explaining severity assignment against rubric",
      "action": "fix_now|fix_in_pr|fix_this_sprint|backlog|defer|false_positive",
      "deduplicated_from": ["string"],
      "false_positive_confidence": "number 0-1 if action is false_positive, else null",
      "refactoring_hint": "string or null"
    }
  ],
  "deferral_candidates": [
    {
      "id": "string",
      "reason": "string explaining why deferred"
    }
  ],
  "false_positive_flags": [
    {
      "id": "string",
      "confidence": "number 0-1",
      "explanation": "string"
    }
  ]
}

## CONSTRAINTS

1. Deduplicate findings that refer to the same root cause, even if reported by different detectors. Keep the most specific instance and note merged IDs.
2. Assign severity strictly according to the provided [SEVERITY_RUBRIC]. Do not upgrade severity because a finding "feels" important.
3. Flag a finding as a false positive only if it matches a pattern in [FALSE_POSITIVE_PATTERNS] or if you can articulate a clear, code-specific reason. Include a confidence score.
4. Defer findings that match [DEFERRAL_PATTERNS] and explain why.
5. For every finding with action "fix_now" or "fix_in_pr", provide a concrete refactoring hint.
6. If the input contains more than [MAX_FINDINGS] findings, prioritize the most severe and note truncation in the summary.
7. Do not invent findings. Only triage what is in [FINDINGS_LIST].

## EXAMPLES

[FEW_SHOT_EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

To adapt this template, start by replacing the placeholders with your actual data. The [FINDINGS_LIST] should be a structured JSON array of smell objects from your detectors. The [SEVERITY_RUBRIC] is critical—paste your team's written definitions for critical, high, medium, and low severity directly into the prompt so the model calibrates against your standards rather than its own defaults. The [FEW_SHOT_EXAMPLES] placeholder should contain at least three worked examples showing correct severity assignment, deduplication decisions, and false positive handling for your codebase. If you are integrating this into a CI pipeline, consider setting [RISK_LEVEL] to "high" to enforce stricter validation and require human review for all critical findings before the report is accepted. For lower-risk internal tools, you can relax this to "medium" and allow automated routing of low-severity items directly to the backlog.

Before deploying this prompt, validate its output against a golden dataset of at least 20 pre-triaged findings that represent your team's actual severity distribution. Run the prompt and compare the model's severity assignments, deduplication choices, and false positive flags against your expected results. Pay special attention to borderline cases where severity could reasonably be argued either way—these are where the model is most likely to drift from your team's norms. If you observe more than 15% disagreement on severity assignments, refine your rubric text or add more few-shot examples until the model aligns. For production use, log every triage report with the model version, prompt hash, and input finding count so you can trace any quality regressions back to prompt or model changes.

This prompt is designed to sit downstream of one or more smell detectors—linters, static analyzers, or other LLM-based detection prompts. It expects a pre-parsed list of findings as input, not raw code. The implementation harness must therefore collect, normalize, and deduplicate findings from multiple sources before invoking the triage prompt. A typical integration point is a CI/CD pipeline step that runs after all detection jobs complete, aggregating their JSON output into a single [FINDINGS_LIST] payload. The harness should enforce a common finding schema (file, line, detector, smell_type, description) across all upstream detectors to ensure the triage prompt receives consistent input.

Validation and retry logic is critical because the triage output drives human review queues and automated merge gates. The harness must validate the model's JSON response against the expected [OUTPUT_SCHEMA]—a list of triaged findings each containing severity, category, action, rationale, and dedup_group fields. If validation fails, retry once with the validation error message appended to the prompt as a correction hint. If the retry also fails, log the raw output and escalate to a human triage lead rather than silently proceeding. For high-risk repositories (infrastructure, security, payments), configure the harness to require explicit human approval on all severity: critical findings before the report is published to the review queue.

Model choice and context window considerations: The triage task requires reasoning across multiple findings to identify duplicates, rank severity relative to other findings, and detect false positive patterns. Use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). The input finding list can grow large in monorepos or broad scans; if the serialized [FINDINGS_LIST] exceeds roughly 60% of the model's context window, split findings by directory or module and run parallel triage passes, then merge results with a final deduplication pass. Logging should capture the prompt version, input finding count, output finding count, validation status, retry count, and any severity distribution shifts for observability into triage quality over time.

Tool integration is optional but powerful. If your review system supports it, expose a publish_triage_report tool that the model can call with the structured output, rather than relying solely on text completion. This reduces parsing errors and lets the harness enforce the schema at the tool-call boundary. For teams using RAG, you can inject a [TEAM_RUBRIC] containing historical severity calibration examples and team-specific false-positive patterns retrieved from past triage decisions. This grounds the model's judgment in your team's actual standards rather than generic severity heuristics. What to avoid: Do not use this prompt on raw code without upstream detection—it will hallucinate findings. Do not skip the deduplication step across detectors before invoking triage, or you will waste context window on redundant entries. Do not treat the triage output as final for critical-path code without human review of the top severity items.