Rule Fire Explanation Prompt for Linter Output

Platform and security engineering teams use this prompt to help developers understand why a static analysis rule fired on their code. Raw linter and SAST output often provides only a rule ID, a severity level, and a line number. Developers who do not understand the rule's intent are more likely to ignore findings, apply incorrect fixes, or suppress the rule entirely. This prompt produces a structured, plain-language explanation that connects the flagged code pattern to the rule's purpose, the potential impact of the violation, and the principle being enforced. It is designed to be wired into CI/CD pipelines, IDE integrations, or internal developer portals where every finding needs a clear, consistent explanation before it reaches a human reviewer.

The ideal user is a platform engineer or DevSecOps practitioner building a developer-facing triage workflow. Required context includes the rule metadata (ID, short description, severity, category), the flagged code snippet with surrounding lines, and optionally the file path and language. The prompt works best when the rule has a documented purpose—if the rule is a custom internal rule without clear intent, the explanation quality degrades and the output should be flagged for human review. Do not use this prompt for findings that require exploitability assessment, risk ranking, or deduplication; those are separate workflows with their own prompts and evaluation criteria.

Before wiring this into a pipeline, define your evaluation criteria: does the explanation accurately capture the rule's intent? Does it connect the specific code pattern to the principle being enforced? Does it avoid hallucinating fix suggestions when none are appropriate? Run a batch of known findings through the prompt and have a security engineer review the explanations for correctness. Flag any explanation that introduces new technical claims not present in the rule definition or code context. For high-severity findings in regulated environments, always route the explanation through a human approval step before it reaches the developer.

This prompt template is the core instruction you send to the model. It is designed to take a linter rule definition and the flagged code snippet, then produce a structured, developer-friendly explanation. The output is organized into four clear sections: the rule's intent, a pattern analysis of the flagged code, the potential impact of leaving the code as-is, and the underlying software engineering principle being enforced. This structure ensures the explanation is both educational and actionable, helping developers understand not just what is wrong, but why it matters.

textCopy
You are a senior developer educator and static analysis expert. Your task is to explain why a specific static analysis rule flagged a piece of code. Your explanation must be accurate, concise, and educational, helping a developer understand the reasoning behind the rule and how to fix the issue.

## INPUT

[RULE_NAME]: The name of the linter rule that fired.
[RULE_DESCRIPTION]: The full description of the rule from the tool's documentation.
[FLAGGED_CODE]: The exact code snippet that triggered the rule.
[CODE_LANGUAGE]: The programming language of the flagged code.

## OUTPUT FORMAT

Produce a JSON object with the following structure. Do not include any text outside the JSON object.

{
  "rule_intent": "A plain-language explanation of what the rule is designed to detect and prevent. Describe the class of bug, security vulnerability, or maintainability issue it targets.",
  "pattern_analysis": "A specific analysis of why the provided [FLAGGED_CODE] matches the rule's pattern. Point to the exact lines, variables, or structures that triggered the rule. Explain the mechanism of the problem in this specific instance.",
  "potential_impact": "A clear description of the concrete negative consequences that could occur if this code pattern is not fixed. Mention specific risks like runtime errors, security breaches, data corruption, or performance degradation. If the risk is low, state that clearly.",
  "underlying_principle": "The broader software engineering or security principle this rule enforces (e.g., 'Principle of Least Privilege', 'Fail Fast', 'Single Responsibility'). Explain how this principle applies to the flagged code."
}

## CONSTRAINTS

- Do not hallucinate. Base your analysis strictly on the provided [RULE_DESCRIPTION] and [FLAGGED_CODE].
- If the [FLAGGED_CODE] appears to be a false positive, explain why it matches the pattern but note any mitigating context that might make it safe.
- Use clear, jargon-free language suitable for a developer who may not be an expert in static analysis.
- The output must be valid JSON.

To adapt this template, replace the placeholders in the ## INPUT section with data from your CI/CD pipeline or static analysis tool. The [RULE_NAME] and [RULE_DESCRIPTION] can be pulled directly from your tool's rule database. The [FLAGGED_CODE] should be the specific lines from the pull request diff that triggered the finding, not the entire file. Before integrating, test this prompt with a golden dataset of known true positives and false positives to ensure the pattern_analysis is precise and the potential_impact is not over- or under-stated. For high-security contexts, always route outputs where the model identifies a potential_impact of 'security breach' for mandatory human review before sending to the developer.

This prompt is designed to sit behind an API endpoint or a CI job that triggers when a static analysis tool (such as Semgrep, CodeQL, or ESLint) flags a finding on a pull request. The application layer is responsible for extracting the rule metadata, the offending code snippet, and the surrounding file context from the linter's output before assembling the prompt. Do not pass raw, untruncated linter logs directly to the model; pre-process the input to include only the specific finding, its location, and the rule definition. This keeps the prompt focused and prevents the model from hallucinating explanations for unrelated findings.

Validation and retries: Parse the model's output against a strict JSON schema that requires the fields rule_id, rule_intent, code_pattern_identified, potential_impact, principle_enforced, and fix_direction. If the output fails schema validation, retry once with a repair prompt that includes the validation error. If the second attempt also fails, log the failure and fall back to a static, rule-author-provided explanation. Model choice: Use a model with strong instruction-following and code reasoning capabilities, such as Claude 3.5 Sonnet or GPT-4o. Avoid smaller or older models that may conflate similar rules or invent plausible-sounding but incorrect explanations. Set temperature to 0.0–0.2 to maximize factual consistency across repeated runs for the same finding.

Logging and review: Log every generated explanation alongside the input finding, the model version, and the prompt template version. For security-critical rules (e.g., those detecting credential leaks, SQL injection, or authentication bypass), route the explanation to a human reviewer before it is shown to the developer. This gate prevents a confidently wrong explanation from misleading a developer into an insecure fix. Integration points: In a developer portal, surface the explanation inline next to the finding. In a CI pipeline, post the explanation as a comment on the PR. In a chat bot, return the explanation as a structured message. In all cases, include a feedback mechanism (thumbs up/down) so the platform team can track explanation quality over time and identify rules that need better static descriptions or prompt tuning.