d20d5e8fb5
Add a proper public-facing documentation site using Mintlify with 19 MDX pages covering getting started, auto mode, commands, configuration, and all user-facing features. Move internal/SDK documentation (Pi SDK, TUI, context & hooks, research notes, ADRs) to docs-internal/ since they should not be part of the public documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2 KiB
2 KiB
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."