gh-yaleh-meta-cc-claude/skills/error-recovery/reference/taxonomy.md

# Error Classification Taxonomy

**Version**: 2.0
**Source**: Bootstrap-003 Error Recovery Methodology
**Last Updated**: 2025-10-18
**Coverage**: 95.4% of observed errors
**Categories**: 13 complete categories

This taxonomy classifies errors systematically for effective recovery and prevention.

---

## Overview

This taxonomy is:
- **MECE** (Mutually Exclusive, Collectively Exhaustive): 95.4% coverage
- **Actionable**: Each category has clear recovery paths
- **Observable**: Each category has detectable symptoms
- **Universal**: 85-90% applicable to other software projects

**Automation Coverage**: 23.7% of errors preventable with 3 automated tools

---

## 13 Error Categories

### Category 1: Build/Compilation Errors (15.0%)

**Definition**: Syntax errors, type mismatches, import issues preventing compilation

**Examples**:
- `cmd/root.go:4:2: "fmt" imported and not used`
- `undefined: someFunction`
- `cannot use x (type int) as type string`

**Common Causes**:
- Unused imports after refactoring
- Type mismatches from incomplete changes
- Missing function definitions
- Syntax errors

**Detection Pattern**: `*.go:[line]:[col]: [error message]`

**Prevention**:
- Pre-commit linting (gofmt, golangci-lint)
- IDE real-time syntax checking
- Incremental compilation

**Recovery**: Fix syntax/type issue, retry `go build`

**Automation Potential**: Medium

---

### Category 2: Test Failures (11.2%)

**Definition**: Unit or integration test assertions that fail during execution

**Examples**:
- `--- FAIL: TestLoadFixture (0.00s)`
- `Fixture content should contain 'sequence' field`
- `FAIL	github.com/project/package	0.003s`

**Common Causes**:
- Test fixture data mismatch
- Assertion failures from code changes
- Missing test data files
- Incorrect expected values

**Detection Pattern**: `--- FAIL:`, `FAIL\t`, assertion messages

**Prevention**:
- Run tests before commit
- Update test fixtures with code changes
- Test-driven development (TDD)

**Recovery**: Update test expectations or fix code

**Automation Potential**: Low (requires understanding test intent)

---

### Category 3: File Not Found (18.7%) ⚠️ AUTOMATABLE

**Definition**: Attempts to access non-existent files or directories

**Examples**:
- `File does not exist.`
- `wc: /path/to/file: No such file or directory`
- `File does not exist. Did you mean file.md?`

**Common Causes**:
- Typos in file paths
- Files moved or deleted
- Incorrect working directory
- Case sensitivity issues

**Detection Pattern**: `File does not exist`, `No such file or directory`

**Prevention**:
- **Automation: `validate-path.sh`** ✅ (prevents 65.2% of category 3 errors)
- Validate paths before file operations
- Use autocomplete for paths
- Check file existence first

**Recovery**: Correct file path, create missing file, or change directory

**Automation Potential**: **HIGH** ✅

---

### Category 4: File Size Exceeded (6.3%) ⚠️ AUTOMATABLE

**Definition**: Attempted to read files exceeding token limit

**Examples**:
- `File content (46892 tokens) exceeds maximum allowed tokens (25000)`
- `File too large to read in single operation`

**Common Causes**:
- Reading large generated files without pagination
- Reading entire JSON files
- Reading log files without limiting lines

**Detection Pattern**: `exceeds maximum allowed tokens`, `File too large`

**Prevention**:
- **Automation: `check-file-size.sh`** ✅ (prevents 100% of category 4 errors)
- Pre-check file size before reading
- Use offset/limit parameters
- Use grep/head/tail instead of full Read

**Recovery**: Use Read with offset/limit, or use grep

**Automation Potential**: **FULL** ✅

---

### Category 5: Write Before Read (5.2%) ⚠️ AUTOMATABLE

**Definition**: Attempted to Write/Edit a file without reading it first

**Examples**:
- `File has not been read yet. Read it first before writing to it.`

**Common Causes**:
- Forgetting to read file before edit
- Reading wrong file, editing intended file
- Session context lost
- Workflow error

**Detection Pattern**: `File has not been read yet`

**Prevention**:
- **Automation: `check-read-before-write.sh`** ✅ (prevents 100% of category 5 errors)
- Always Read before Write/Edit
- Use Edit instead of Write for existing files
- Check read history

**Recovery**: Read the file, then retry Write/Edit

**Automation Potential**: **FULL** ✅

---

### Category 6: Command Not Found (3.7%)

**Definition**: Bash commands that don't exist or aren't in PATH

**Examples**:
- `/bin/bash: line 1: meta-cc: command not found`
- `command not found: gofmt`

**Common Causes**:
- Binary not built yet
- Binary not in PATH
- Typo in command name
- Required tool not installed

**Detection Pattern**: `command not found`

**Prevention**:
- Build before running commands
- Verify tool installation
- Use absolute paths for project binaries

**Recovery**: Build binary, install tool, or correct command

**Automation Potential**: Medium

---

### Category 7: JSON Parsing Errors (6.0%)

**Definition**: Malformed JSON or schema mismatches

**Examples**:
- `json: cannot unmarshal string into Go struct field`
- `invalid character '}' looking for beginning of value`

**Common Causes**:
- Schema changes without updating code
- Malformed JSON in test fixtures
- Type mismatches
- Missing or extra commas/braces

**Detection Pattern**: `json:`, `unmarshal`, `invalid character`

**Prevention**:
- Validate JSON with jq before use
- Use JSON schema validation
- Test JSON fixtures with actual code

**Recovery**: Fix JSON structure or update schema

**Automation Potential**: Medium

---

### Category 8: Request Interruption (2.2%)

**Definition**: User manually interrupted tool execution

**Examples**:
- `[Request interrupted by user for tool use]`
- `Command aborted before execution`

**Common Causes**:
- User realized mistake mid-execution
- User wants to change approach
- Long-running command needs stopping

**Detection Pattern**: `interrupted by user`, `aborted before execution`

**Prevention**: Not applicable (user decision)

**Recovery**: Not needed (intentional)

**Automation Potential**: N/A

---

### Category 9: MCP Server Errors (17.1%)

**Definition**: Errors from Model Context Protocol tool integrations

**Subcategories**:
- 9a. Connection Errors (server unavailable)
- 9b. Timeout Errors (query exceeds time limit)
- 9c. Query Errors (invalid parameters)
- 9d. Data Errors (unexpected format)

**Examples**:
- `MCP server connection failed`
- `Query timeout after 30s`
- `Invalid parameter: status must be 'error' or 'success'`

**Common Causes**:
- MCP server not running
- Network issues
- Query too broad
- Invalid parameters
- Schema changes

**Prevention**:
- Check MCP server status before queries
- Use pagination for large queries
- Validate query parameters
- Handle connection errors gracefully

**Recovery**: Restart MCP server, optimize query, or fix parameters

**Automation Potential**: Medium

---

### Category 10: Permission Denied (0.7%)

**Definition**: Insufficient permissions to access file or execute command

**Examples**:
- `Permission denied: /path/to/file`
- `Operation not permitted`

**Common Causes**:
- File permissions too restrictive
- Directory not writable
- User doesn't own file

**Detection Pattern**: `Permission denied`, `Operation not permitted`

**Prevention**:
- Verify permissions before operations
- Use appropriate user context
- Avoid modifying system files

**Recovery**: Change permissions (chmod/chown)

**Automation Potential**: Low

---

### Category 11: Empty Command String (1.1%)

**Definition**: Bash tool invoked with empty or whitespace-only command

**Examples**:
- `/bin/bash: line 1: : command not found`

**Common Causes**:
- Variable expansion to empty string
- Conditional command construction error
- Copy-paste error

**Detection Pattern**: `/bin/bash: line 1: : command not found`

**Prevention**:
- Validate command strings are non-empty
- Check variable values
- Use bash -x to debug

**Recovery**: Provide valid command string

**Automation Potential**: High

---

### Category 12: Go Module Already Exists (0.4%)

**Definition**: Attempted `go mod init` when go.mod already exists

**Examples**:
- `go: /path/to/go.mod already exists`

**Common Causes**:
- Forgot to check for existing go.mod
- Re-running initialization script

**Detection Pattern**: `go.mod already exists`

**Prevention**:
- Check for go.mod existence before init
- Idempotent scripts

**Recovery**: No action needed

**Automation Potential**: Full

---

### Category 13: String Not Found (Edit Errors) (3.2%)

**Definition**: Edit tool attempts to replace non-existent string

**Examples**:
- `String to replace not found in file.`
- `String: {old content} not found`

**Common Causes**:
- File changed since last inspection (stale old_string)
- Whitespace differences (tabs vs spaces)
- Line ending differences (LF vs CRLF)
- Copy-paste errors

**Detection Pattern**: `String to replace not found in file`

**Prevention**:
- Re-read file immediately before Edit
- Use exact string copies
- Include sufficient context in old_string
- Verify file hasn't changed

**Recovery**:
1. Re-read file to get current content
2. Locate target section
3. Copy exact current string
4. Retry Edit with correct old_string

**Automation Potential**: High

---

## Uncategorized Errors (4.6%)

**Remaining**: 61 errors

**Breakdown**:
- Low-frequency unique errors: ~35 errors (2.6%)
- Rare edge cases: ~15 errors (1.1%)
- Other tool-specific errors: ~11 errors (0.8%)

These occur too infrequently (<0.5% each) to warrant dedicated categories.

---

## Automation Summary

**Automated Prevention Available**:
| Category | Errors | Tool | Coverage |
|----------|--------|------|----------|
| File Not Found | 250 (18.7%) | `validate-path.sh` | 65.2% |
| File Size Exceeded | 84 (6.3%) | `check-file-size.sh` | 100% |
| Write Before Read | 70 (5.2%) | `check-read-before-write.sh` | 100% |
| **Total Automated** | **317 (23.7%)** | **3 tools** | **Weighted avg** |

**Automation Speedup**: 20.9x for automated categories

---

## Transferability

**Universal Categories** (90-100% transferable):
- Build/Compilation Errors
- Test Failures
- File Not Found
- File Size Limits
- Permission Denied
- Empty Command

**Portable Categories** (70-90% transferable):
- Command Not Found
- JSON Parsing
- String Not Found

**Context-Specific Categories** (40-70% transferable):
- Write Before Read (Claude Code specific)
- Request Interruption (AI assistant specific)
- MCP Server Errors (MCP-enabled systems)
- Go Module Exists (Go-specific)

**Overall Transferability**: ~85-90%

---

## Usage

### For Developers

1. **Error occurs** → Match to category using detection pattern
2. **Review common causes** → Identify root cause
3. **Apply prevention** → Check if automated tool available
4. **Execute recovery** → Follow category-specific steps

### For Tool Builders

1. **High automation potential** → Prioritize Categories 3, 4, 5, 11, 12
2. **Medium automation** → Consider Categories 6, 7, 9
3. **Low automation** → Manual handling for Categories 2, 8, 10

### For Project Adaptation

1. **Start with universal categories** (1-7, 10, 11, 13)
2. **Adapt context-specific** (8, 9, 12)
3. **Monitor uncategorized** → Create new categories if patterns emerge

---

**Source**: Bootstrap-003 Error Recovery Methodology
**Framework**: BAIME (Bootstrapped AI Methodology Engineering)
**Status**: Production-ready, validated with 1336 errors
**Coverage**: 95.4% (converged)