# Error Classification Reference

> **Loaded by:** apex step-03-execute (build failure) and step-04-examine (validation)
> **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
> **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
> **Moved from:** `business-analyse-develop/references/error-classification.md` (delegation refactoring)

---

## Error Categories

### Category A: Missing NuGet Package (FIX = `dotnet add package`)

> **These errors CANNOT be fixed by editing source code. Do NOT waste iterations trying.**

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | `Could not load file or assembly 'Microsoft.Extensions.Http.Resilience, Version=10.2.0.0'` | `dotnet add package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
| `error CS0246: The type or namespace name '{Type}' could not be found` (after restore) | `The type or namespace name 'Polly' could not be found` | `dotnet add package {PackageName}` |
| `error NU1101: Unable to find package {Name}` | Package source misconfigured | Check `nuget.config` sources |

**Detection heuristic:** If `dotnet build` fails with CS0246 and the missing type is NOT in any project file (grep across `src/`), it is a missing package, not a missing `using` statement.

**Fix procedure:**
1. Extract package name from error message
2. Run `dotnet add {TargetProject} package {PackageName}`
3. Run `dotnet restore`
4. Rebuild -- if still failing, the version may need to be pinned

---

### Category B: Version Mismatch (FIX = update package version)

> **These errors CANNOT be fixed by editing source code.**

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | Type exists in different version | `dotnet add package {Asm} --version {CorrectVersion}` |
| `MissingMethodException: Method not found: '{Method}'` | Method signature changed between versions | Update to version that has the method |
| `NU1605: Detected package downgrade` | Version conflict in dependency tree | Align all references to same version |
| `FileLoadException: Could not load file or assembly '{Name}'. The located assembly's manifest definition does not match the assembly reference.` | Wrong version loaded | Pin correct version in .csproj |

**Fix procedure:**
1. Identify the assembly/package name
2. Run `dotnet list package --include-transitive` to see actual resolved version
3. If conflict: add explicit `<PackageReference>` with correct version
4. Rebuild

---

### Category C: Missing DI Registration (FIX = edit DI configuration)

> **These errors require editing `DependencyInjection.cs` or `Program.cs`, NOT the service/interface code.**

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `InvalidOperationException: Unable to resolve service for type '{Interface}'` | Missing `services.AddScoped<IFoo, Foo>()` | Add DI registration |
| `InvalidOperationException: No service for type '{Type}' has been registered` | Same as above | Same |
| `InvalidOperationException: Unable to resolve service for type '{Type}' while attempting to activate '{Consumer}'` | Consumer's dependency not registered | Register the missing dependency |

**Fix procedure:**
1. Extract the interface/type name from error
2. Find the implementation class (grep for `class.*: {Interface}`)
3. Add `services.AddScoped<{Interface}, {Implementation}>()` to appropriate DI file
4. Rebuild

---

### Category D: Database/Migration (FIX = run migration commands)

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `SqlException: Invalid object name '{TableName}'` | Table does not exist | `dotnet ef database update` |
| `SqlException: Invalid column name '{Column}'` | Column not in schema | Create and apply migration |
| `RelationalEventId.PendingModelChangesWarning` | Model changed, no migration | `dotnet ef migrations add {Name}` |

---

### Category E: Configuration (FIX = edit appsettings.json)

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `InvalidOperationException: The ConnectionString property has not been initialized` | Missing connection string | Add to `appsettings.json` |
| `ArgumentNullException: Value cannot be null. (Parameter 'connectionString')` | Same | Same |
| `OptionsValidationException: Validation failed for '{Section}'` | Missing required config section | Add section to `appsettings.json` |

---

### Category F: Code Error (FIX = edit source code)

> **Only this category should trigger code editing in business-analyse-develop iterations.**

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `error CS0246` + type IS in a project file | Missing `using` statement | Add `using {Namespace};` |
| `error CS1061` | Method does not exist on type | Fix method call or add method |
| `error CS0103` | Name does not exist in current context | Fix variable/method reference |
| `error CS0029` | Cannot implicitly convert type | Fix type mismatch |
| Test assertion failures | `Assert.Equal` fails | Fix source code (not tests) |

---

### Category G: PRD Quality Error (FIX = fix PRD or re-run handoff)

> **These errors are NOT caused by code generation — they originate from invalid PRD data.**
> The handoff generated file paths with illegal characters (spaces, apostrophes, accents in entity names).
> Code generation faithfully reproduced the invalid paths → build failure.

| Error Pattern | Example | Fix |
|--------------|---------|-----|
| `error CS1001: Identifier expected` with file name containing spaces | `Type d'absence.cs` → CS1001 | Re-run `/business-analyse-handoff` with entity canonicalization |
| `error CS1513/CS1514` with file name containing apostrophes | `Congé.cs` → accent in identifier | Fix entity name in BA or re-run handoff |
| Path contains non-ASCII characters in `.cs` file names | `Département.cs` | Canonicalize: strip diacritics, PascalCase |

**Detection heuristic:** If the error file path contains spaces, apostrophes, or accented characters, it is a PRD quality error, not a code error. Do NOT attempt to fix the generated code — fix the PRD source.

**Fix procedure:**
1. Identify the invalid entity name from the error file path
2. Report to user: "PRD quality error — entity name '{name}' is not a valid C# identifier"
3. Either: manually canonicalize in the PRD file, or re-run `/business-analyse-handoff` (which now includes canonicalization)
4. Re-run `/apex -d` with the corrected PRD

---

## Decision Tree

When a build or runtime error occurs, follow this tree:

```
BUILD/RUNTIME ERROR
  |
  +-- Contains "Could not load file or assembly" ?
  |     YES -> Category A or B (NEVER edit source code)
  |     Extract package name -> dotnet add package -> rebuild
  |
  +-- Contains "Unable to resolve service" ?
  |     YES -> Category C (edit DI config ONLY)
  |     Find implementation -> add registration -> rebuild
  |
  +-- Contains "SqlException" or "Invalid object name" ?
  |     YES -> Category D (run migrations)
  |     dotnet ef migrations add / database update
  |
  +-- Contains "ConnectionString" or "OptionsValidation" ?
  |     YES -> Category E (edit config files)
  |
  +-- error CS#### (C# compiler error) ?
  |     YES -> Does the error file path contain spaces, apostrophes, or accents?
  |           YES -> Category G (PRD quality error — fix handoff, not code)
  |           NO  -> Is the missing type in ANY project file?
  |                 NO  -> Category A (missing package)
  |                 YES -> Category F (fix source code)
  |
  +-- Test failure (Assert/Expected) ?
        YES -> Category F (fix source code, NOT tests)
```

---

## Ralph-Loop Integration Rules

1. **Before ANY code fix attempt:** Classify the error using the decision tree above
2. **Categories A, B:** Run package commands IMMEDIATELY. Do NOT count as a "fix iteration"
3. **Category C:** Edit DI file only. One targeted fix, rebuild, verify
4. **Category D:** Run migration commands. Do NOT edit code
5. **Category E:** Edit config file only
6. **Category F:** Normal business-analyse-develop code fix iteration
7. **If 2+ consecutive iterations fail on same error after code fixes -> re-classify** (likely wrong category)
