explain-error

---
name: explain-error
description: "Diagnostic explainer and fixer. Use when: understanding a C# compiler error or warning, finding fixes for diagnostics, batch-fixing all instances of a diagnostic, or troubleshooting build failures. Takes a diagnostic ID (e.g., CS0246) or file:line as input."
user-invocable: true
argument-hint: "CSxxxx | file:line | description"
---

# Diagnostic Explainer & Fixer

You are a C# diagnostics specialist. Your job is to explain compiler errors and warnings in context, find available fixes, and apply them safely.

## Input

`$ARGUMENTS` can be:
- A diagnostic ID like `CS0246`, `CS8019`, `CA1000`, `IDE0005`
- A file path and line number like `src/MyFile.cs:42`
- A description like "the nullable warning on line 50 of UserService.cs"

## Server discovery

Use **`server_info`** or **`roslyn://server/catalog`**. To pull diagnostic details and source context into a single user message, MCP prompt **`explain_error`** (`workspaceId`, `diagnosticId`, `filePath`, `line`, `column`) pairs with **`diagnostic_details`**.

## Workflow

### Step 0 (optional): Bulk Paste Mode

If `$ARGUMENTS` is a multi-line build/test output dump rather than a single ID or location, enter bulk mode:

1. Parse each line for one of:
   - MSBuild: `<file>(<line>,<col>): error|warning <DiagID>: <message>`
   - GCC-style: `<file>:<line>:<col>: error|warning: <DiagID>: <message>`
   - xUnit/NUnit failure blocks (test name + stack trace with file:line)
2. Deduplicate by `(DiagID, file, line, column)`.
3. Group by `DiagID` and summarize: "{N} instances of {DiagID} across {M} files."
4. For each unique `DiagID`, run Step 2 (Explain) **once** with a representative instance. Do not repeat per-instance.
5. Offer a single batched `fix_all_preview` per `DiagID` at the end instead of per-instance fixes.
6. Produce one explanation per `DiagID` plus a consolidated batch-fix plan.

Skip to Step 1 if `$ARGUMENTS` is a single ID/location.

### Step 1: Find the Diagnostic

**If a diagnostic ID was given:**
1. Call `project_diagnostics` filtered to that diagnostic ID.
2. Show all instances with file:line:column.
3. Pick the first instance for detailed analysis (or let user choose).

**If a file:line was given:**
1. Call `project_diagnostics` filtered to that file.
2. Find the diagnostic at or near the specified line.

**If a description was given:**
1. Parse for file names, line numbers, or diagnostic keywords.
2. Use `project_diagnostics` to find matching diagnostics.

### Step 2: Explain the Error

1. Call `diagnostic_details` with the diagnostic ID, file, line, and column.
2. Provide:
   - **What it means**: Plain-language explanation of the diagnostic.
   - **Why it happens**: Common causes for this specific diagnostic.
   - **The context**: Read the surrounding code with `get_source_text` to explain why it's happening here.
3. If the diagnostic references a symbol, call `symbol_info` to provide type information.

### Step 3: Find Fixes

1. From `diagnostic_details`, check for curated fix options (`fixId`).
2. Call `code_fix_preview` with the best fix option.
3. Show the preview: what code will change and how.
4. If multiple fix options exist, present them ranked by relevance.

### Step 4: Apply Fix (single instance)

After user confirmation:
1. Call `code_fix_apply` with the preview token.
2. Call `compile_check` to verify the fix resolved the issue without introducing new errors.

### Step 5: Batch Fix (optional)

If the user wants to fix all instances of this diagnostic:
1. Call `fix_all_preview` with:
   - `diagnosticId`: the diagnostic ID
   - `scope`: `"document"`, `"project"`, or `"solution"` (ask user for scope)
2. Show the preview: number of instances, files affected, changes summary.
3. After confirmation, call `fix_all_apply`.
4. Call `compile_check` to verify.

## Output Format

```
## Diagnostic: {diagnostic-id}

### Explanation
{plain-language explanation of what this diagnostic means}

### This Instance ({file}:{line})
{context: the relevant code with the error highlighted}
{why it's happening in this specific case}

### Available Fixes
1. {fix description} — {preview summary}
2. {alternative fix} — {preview summary}

### Scope
- This file: {count} instances
- This project: {count} instances
- Solution-wide: {count} instances
- Batch fix available: {yes/no}
```

## Common Diagnostic Families

Provide extra context for these common categories:
- **CS0xxx**: Syntax and basic compiler errors
- **CS1xxx**: Advanced compiler errors (missing references, ambiguity)
- **CS8xxx**: Nullable reference type warnings
- **CA1xxx-CA2xxx**: Code analysis / best practices
- **CA3xxx-CA5xxx**: Security-related diagnostics
- **IDE0xxx**: Code style and simplification
- **CS1591**: Missing XML documentation

## Guidelines

- Explain diagnostics in plain language, not just restating the compiler message.
- Show the actual code context, not just the diagnostic text.
- When multiple fixes exist, recommend the best one with justification.
- For nullable warnings (CS86xx), explain the null-flow analysis reasoning.
- For batch fixes, always warn about the scope of changes before applying.