Initial commit

skills/error-recovery/reference/taxonomy.md

@@ -0,0 +1,461 @@
+# 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)