Errors And Discoverability
Error quality, retry guidance, schema discovery, and versioning.
Failure modes: 5 active | 🟠 3 high · 🟡 2 medium
| File | Severity | Summary |
|---|---|---|
| 18-high-error-quality.md | 🟠 High | When a command fails, the agent needs to understand: what failed, why, and what to do next |
| 19-high-retry-hints.md | 🟠 High | When a command fails, the agent decides: retry immediately, retry after delay, retry with different args, or give up |
| 22-high-schema-versioning.md | 🟠 High | Agents built against a tool's output schema break silently when that schema changes |
| 20-medium-dependency-discovery.md | 🟡 Medium | CLI tools often depend on external tools, services, or specific environment configurations |
| 21-medium-schema-discoverability.md | 🟡 Medium | Agents need to know what commands exist, what parameters they accept, and what they return — without running commands... |
Detailed Metrics
| Challenge | Severity | Frequency | Detectability | Token Spend | Time | Context |
|---|---|---|---|---|---|---|
| §18 | 🟠 High | Very Common | Easy | High | Medium | High |
| §19 | 🟠 High | Very Common | Medium | High | High | Medium |
| §22 | 🟠 High | Common | Hard | High | High | Medium |
| §20 | 🟡 Medium | Common | Easy | Medium | Medium | Low |
| §21 | 🟡 Medium | Very Common | Easy | High | Medium | Medium |