872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
28 lines
2 KiB
Markdown
28 lines
2 KiB
Markdown
# Error Taxonomy & Routing
|
|
|
|
**The key insight:** Different errors have fundamentally different causes and optimal resolution strategies. Treating them uniformly is one of the biggest sources of wasted iterations.
|
|
|
|
### The Optimal Taxonomy
|
|
|
|
| Error Class | Context Needed | Optimal Handler | Escalation |
|
|
|-------------|---------------|-----------------|------------|
|
|
| **Syntax/Type** | Error message + offending file + types | Deterministic fast path (no LLM needed) | Only if fast path fails |
|
|
| **Logic** | Failing test (expected vs actual) + implementation + spec | LLM with medium, focused context | After 3 attempts |
|
|
| **Design** | Original spec + architecture + interface contracts + implementation | LLM with broad context | Often needs human input |
|
|
| **Performance** | Profiling data + benchmarks + code | Specialist optimization agent | If regression >2x |
|
|
| **Security** | Static analysis results + secure pattern reference | Conservative fix prompt | Always flag for review |
|
|
| **Environment** | Environment config + recent dep changes + error output | Specialized env context | If not auto-resolved |
|
|
| **Flaky Tests** | Run test multiple times to confirm flakiness | Quarantine, don't fix | Infrastructure agent |
|
|
|
|
### Critical Routing Rules
|
|
|
|
- **Flaky tests:** Detect by running failing tests multiple times. If inconsistent, **quarantine** — never trigger a fix cycle.
|
|
- **Environment errors:** Classify as potentially environmental when they appear in build/startup rather than tests.
|
|
- **Security:** Caught by static analysis in the deterministic layer, not by the LLM. Run security linting after every task.
|
|
- **Syntax/Type:** Hit a deterministic fast path first. Missing import? Search codebase for the export. Only escalate to LLM if mechanical fix fails.
|
|
|
|
### The Architecture
|
|
|
|
The orchestrator classifies every error → selects the appropriate context assembly strategy → optionally selects a different prompt framing. The agent experiences this as *"I got exactly the information I need"* rather than *"I got a dump of everything."*
|
|
|
|
---
|