Compiler Error Explanation and Fix Prompt

This prompt is designed for developers and build engineers who are staring at a compiler or linker error that is difficult to parse. It is not a general-purpose code explainer. Use it when a build fails with an error message that is verbose, template-heavy, or toolchain-specific, and you need a plain-language diagnosis, a ranked list of root causes, and concrete fix candidates grounded in the actual codebase. The ideal user is someone who understands the code but is blocked by an opaque error message from gcc, rustc, clang, javac, go build, or a similar toolchain. The prompt assumes you can provide the raw error output, the failing source file, and relevant build configuration (e.g., CMakeLists.txt, Cargo.toml, Makefile, or compiler flags). It is most effective when the error is deterministic and reproducible, not when the failure is intermittent or environment-specific without logs.

This prompt belongs in a workflow where the AI has access to the error output, the failing file, and relevant build configuration. It is not a replacement for reading the documentation, but it accelerates the diagnostic loop by structuring the investigation before you open a browser tab. The prompt template uses square-bracket placeholders for [ERROR_OUTPUT], [FAILING_FILE], [BUILD_CONFIG], and [CODEBASE_CONTEXT] so you can wire it into a CI/CD pipeline, a CLI tool, or an IDE plugin. For high-risk production systems, always require human review of any suggested fix before applying it, and validate that the fix compiles against the actual codebase context. Do not use this prompt for runtime errors, logical bugs, or performance issues—those require different diagnostic workflows.

Before using this prompt, confirm you have the full error output (not a truncated snippet), the source file that triggered the error, and any relevant build configuration files. If you only have a partial error message or cannot share the source file, the prompt will produce lower-quality results. After receiving the AI's diagnosis, verify the top-ranked root cause by applying the suggested fix in a local branch and running the build. If the fix does not resolve the error, feed the new error output back into the prompt for a revised diagnosis. Avoid applying multiple fixes at once, as this makes it impossible to isolate which change resolved the issue.

This prompt template is designed to be pasted directly into your AI coding agent or development harness. It takes a raw compiler or linker error, along with optional source context and build configuration, and produces a structured diagnosis. The output includes a plain-language explanation, a ranked list of root causes, concrete fix candidates with code snippets, and a toolchain misconfiguration check. Replace every square-bracket placeholder with real values before sending the prompt to the model.

textCopy
You are a senior systems engineer and compiler specialist. Your task is to analyze a compiler or linker error and produce a structured diagnosis.

## INPUT
[ERROR_LOG]

## OPTIONAL CONTEXT
- Source file(s) where the error occurred: [SOURCE_FILES]
- Build system and compiler version: [BUILD_SYSTEM]
- Recent changes that may have triggered the error: [RECENT_CHANGES]
- Build configuration flags: [BUILD_FLAGS]

## OUTPUT SCHEMA
Return a JSON object with the following fields:
{
  "error_summary": "One-sentence plain-language summary of what the error means.",
  "root_causes": [
    {
      "cause": "Description of a likely root cause.",
      "probability": "high|medium|low",
      "evidence": "Specific lines or patterns from the error log that support this cause."
    }
  ],
  "fix_candidates": [
    {
      "fix": "Description of the fix.",
      "code_snippet": "Concrete code change or build configuration change.",
      "applies_to": "File path or build target this fix applies to.",
      "verification": "Command or test to run to confirm the fix worked."
    }
  ],
  "toolchain_misconfiguration_check": {
    "is_likely_toolchain_issue": true|false,
    "explanation": "If true, explain why this looks like a toolchain or environment problem rather than a code defect.",
    "checks": ["Specific checks to run: compiler version, path, environment variables, etc."]
  },
  "confidence": "high|medium|low",
  "additional_context_needed": ["Questions to ask the developer if more information would improve the diagnosis."]
}

## CONSTRAINTS
- Do not invent compiler flags, error codes, or toolchain behaviors you are uncertain about. Mark uncertain claims with [UNCERTAIN].
- Rank root causes by probability. Do not list more than five.
- Every fix candidate must include a verification step.
- If the error log is incomplete or ambiguous, state what additional information is needed in `additional_context_needed`.
- If the error clearly indicates a toolchain misconfiguration (wrong compiler version, missing system headers, broken symlinks, corrupted cache), set `is_likely_toolchain_issue` to true and prioritize environment checks over code changes.
- Prefer fixes that are minimal and reversible.

To adapt this template for your workflow, replace the placeholders with real data from your build system. The [ERROR_LOG] placeholder should contain the full, unredacted compiler or linker output. If you have source file access, include the relevant files or snippets in [SOURCE_FILES]. For CI/CD integration, wire [BUILD_SYSTEM] and [BUILD_FLAGS] from your build configuration automatically. The output schema is designed to be machine-readable so you can parse the JSON response and surface fix candidates directly in your IDE or PR review interface. Always validate the JSON output against the schema before presenting it to developers, and consider adding a human review step when the model's confidence is low or when the fix involves production build configuration changes.

This prompt is designed to be called programmatically, not just pasted into a chat window. The most effective integration point is a CI failure handler or a pre-commit hook that captures the raw compiler output, the failing file, and a snapshot of the build environment. The prompt expects three structured inputs: [COMPILER_OUTPUT] (the raw error text), [SOURCE_CONTEXT] (the file or region where the error originated), and [BUILD_ENVIRONMENT] (toolchain version, OS, and relevant flags). When wiring this into an application, never pass the entire repository as context; instead, extract the specific translation unit, its immediate includes, and any recently modified files in the same module. This keeps latency low and prevents the model from hallucinating fixes in unrelated code.

For production use, wrap the model call in a validation harness that checks the output schema before surfacing suggestions. The expected output is a JSON object with error_explanation, root_causes (a ranked array with cause, probability, and evidence), and fix_candidates (an array with description, code_snippet, and verification_command). After receiving the response, run a structural validator that confirms every fix_candidate includes a non-empty code_snippet and that verification_command references a real build target. If the model returns a fix that suggests modifying a file outside the provided [SOURCE_CONTEXT], flag it for human review. For high-risk codebases, add a mandatory approval gate: the harness should post the top-ranked fix as a draft patch or PR comment, not apply it automatically. Log every model response alongside the compiler output and the final resolution so you can build a regression dataset over time.

Model choice matters here. Use a model with strong code reasoning and a large context window—Claude 3.5 Sonnet or GPT-4o are good defaults. Avoid small or general-purpose models that will hallucinate compiler flags or confuse GCC and Clang error codes. Set temperature to 0 or very low to keep root-cause rankings stable across runs. If the prompt is part of a coding agent loop, implement a retry budget: allow one retry if the output fails schema validation, but escalate to a human if the second attempt also fails or if the model's confidence in its top-ranked cause drops below a threshold you define. Finally, never feed compiler output that contains absolute file paths, secrets, or internal hostnames directly into a third-party model API without redaction. Strip paths to repository-relative form and scrub environment variables before sending.