Initial commit
This commit is contained in:
Zhongwei Li
418
skills/error-recovery/reference/recovery-patterns.md
Normal file
418
skills/error-recovery/reference/recovery-patterns.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# Recovery Strategy Patterns
|
||||
|
||||
**Version**: 1.0
|
||||
**Source**: Bootstrap-003 Error Recovery Methodology
|
||||
**Last Updated**: 2025-10-18
|
||||
|
||||
This document provides proven recovery patterns for each error category.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Syntax Error Fix-and-Retry
|
||||
|
||||
**Applicable to**: Build/Compilation Errors (Category 1)
|
||||
|
||||
**Strategy**: Fix syntax error in source code and rebuild
|
||||
|
||||
**Steps**:
|
||||
1. **Locate**: Identify file and line from error (`file.go:line:col`)
|
||||
2. **Read**: Read the problematic file section
|
||||
3. **Fix**: Edit file to correct syntax error
|
||||
4. **Verify**: Run `go build` or `go test`
|
||||
5. **Retry**: Retry original operation
|
||||
|
||||
**Automation**: Semi-automated (detection automatic, fix manual)
|
||||
|
||||
**Success Rate**: >90%
|
||||
|
||||
**Time to Recovery**: 2-5 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: cmd/root.go:4:2: "fmt" imported and not used
|
||||
|
||||
Recovery:
|
||||
1. Read cmd/root.go
|
||||
2. Edit cmd/root.go - remove line 4: import "fmt"
|
||||
3. Bash: go build
|
||||
4. Verify: Build succeeds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Test Fixture Update
|
||||
|
||||
**Applicable to**: Test Failures (Category 2)
|
||||
|
||||
**Strategy**: Update test fixtures or expectations to match current code
|
||||
|
||||
**Steps**:
|
||||
1. **Analyze**: Understand test expectation vs code output
|
||||
2. **Decide**: Determine if code or test is incorrect
|
||||
3. **Update**: Fix code or update test fixture/assertion
|
||||
4. **Verify**: Run test again
|
||||
5. **Full test**: Run complete test suite
|
||||
|
||||
**Automation**: Low (requires human judgment)
|
||||
|
||||
**Success Rate**: >85%
|
||||
|
||||
**Time to Recovery**: 5-15 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: --- FAIL: TestLoadFixture (0.00s)
|
||||
fixtures_test.go:34: Missing 'sequence' field
|
||||
|
||||
Recovery:
|
||||
1. Read tests/fixtures/sample-session.jsonl
|
||||
2. Identify missing 'sequence' field
|
||||
3. Edit fixture to add 'sequence' field
|
||||
4. Bash: go test ./internal/testutil -v
|
||||
5. Verify: Test passes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Path Correction ⚠️ AUTOMATABLE
|
||||
|
||||
**Applicable to**: File Not Found (Category 3)
|
||||
|
||||
**Strategy**: Correct file path or create missing file
|
||||
|
||||
**Steps**:
|
||||
1. **Verify**: Confirm file doesn't exist (`ls` or `find`)
|
||||
2. **Locate**: Search for file with correct name
|
||||
3. **Decide**: Path typo vs file not created
|
||||
4. **Fix**:
|
||||
- If typo: Correct path
|
||||
- If not created: Create file or reorder workflow
|
||||
5. **Retry**: Retry with correct path
|
||||
|
||||
**Automation**: High (path validation, fuzzy matching, "did you mean?")
|
||||
|
||||
**Success Rate**: >95%
|
||||
|
||||
**Time to Recovery**: 1-3 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: No such file: /path/internal/testutil/fixture.go
|
||||
|
||||
Recovery:
|
||||
1. Bash: ls /path/internal/testutil/
|
||||
2. Find: File is fixtures.go (not fixture.go)
|
||||
3. Bash: wc -l /path/internal/testutil/fixtures.go
|
||||
4. Verify: Success
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Read-Then-Write ⚠️ AUTOMATABLE
|
||||
|
||||
**Applicable to**: Write Before Read (Category 5)
|
||||
|
||||
**Strategy**: Add Read step before Write, or use Edit
|
||||
|
||||
**Steps**:
|
||||
1. **Check existence**: Verify file exists
|
||||
2. **Decide tool**:
|
||||
- For modifications: Use Edit
|
||||
- For complete rewrite: Read then Write
|
||||
3. **Read**: Read existing file content
|
||||
4. **Write/Edit**: Perform operation
|
||||
5. **Verify**: Confirm desired content
|
||||
|
||||
**Automation**: Fully automated (can auto-insert Read step)
|
||||
|
||||
**Success Rate**: >98%
|
||||
|
||||
**Time to Recovery**: 1-2 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: File has not been read yet.
|
||||
|
||||
Recovery:
|
||||
1. Bash: ls internal/testutil/fixtures.go
|
||||
2. Read internal/testutil/fixtures.go
|
||||
3. Edit internal/testutil/fixtures.go
|
||||
4. Verify: Updated successfully
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Build-Then-Execute
|
||||
|
||||
**Applicable to**: Command Not Found (Category 6)
|
||||
|
||||
**Strategy**: Build binary before executing, or add to PATH
|
||||
|
||||
**Steps**:
|
||||
1. **Identify**: Determine missing command
|
||||
2. **Check buildable**: Is this a project binary?
|
||||
3. **Build**: Run build command (`make build`)
|
||||
4. **Execute**: Use local path or install to PATH
|
||||
5. **Verify**: Command executes
|
||||
|
||||
**Automation**: Medium (can detect and suggest build)
|
||||
|
||||
**Success Rate**: >90%
|
||||
|
||||
**Time to Recovery**: 2-5 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: meta-cc: command not found
|
||||
|
||||
Recovery:
|
||||
1. Bash: ls meta-cc (check if exists)
|
||||
2. If not: make build
|
||||
3. Bash: ./meta-cc --version
|
||||
4. Verify: Command runs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 6: Pagination for Large Files ⚠️ AUTOMATABLE
|
||||
|
||||
**Applicable to**: File Size Exceeded (Category 4)
|
||||
|
||||
**Strategy**: Use offset/limit or alternative tools
|
||||
|
||||
**Steps**:
|
||||
1. **Detect**: File size check before read
|
||||
2. **Choose approach**:
|
||||
- **Option A**: Read with offset/limit
|
||||
- **Option B**: Use grep/head/tail
|
||||
- **Option C**: Process in chunks
|
||||
3. **Execute**: Apply chosen approach
|
||||
4. **Verify**: Obtained needed information
|
||||
|
||||
**Automation**: Fully automated (can auto-detect and paginate)
|
||||
|
||||
**Success Rate**: 100%
|
||||
|
||||
**Time to Recovery**: 1-2 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: File exceeds 25000 tokens
|
||||
|
||||
Recovery:
|
||||
1. Bash: wc -l large-file.jsonl # Check size
|
||||
2. Read large-file.jsonl offset=0 limit=1000 # Read first 1000 lines
|
||||
3. OR: Bash: head -n 1000 large-file.jsonl
|
||||
4. Verify: Got needed content
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 7: JSON Schema Fix
|
||||
|
||||
**Applicable to**: JSON Parsing Errors (Category 7)
|
||||
|
||||
**Strategy**: Fix JSON structure or update schema
|
||||
|
||||
**Steps**:
|
||||
1. **Validate**: Use `jq` to check JSON validity
|
||||
2. **Locate**: Find exact parsing error location
|
||||
3. **Analyze**: Determine if JSON or code schema is wrong
|
||||
4. **Fix**:
|
||||
- If JSON: Fix structure (commas, braces, types)
|
||||
- If schema: Update Go struct tags/types
|
||||
5. **Test**: Verify parsing succeeds
|
||||
|
||||
**Automation**: Medium (syntax validation yes, schema fix no)
|
||||
|
||||
**Success Rate**: >85%
|
||||
|
||||
**Time to Recovery**: 3-8 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: json: cannot unmarshal string into field .count of type int
|
||||
|
||||
Recovery:
|
||||
1. Read testdata/fixture.json
|
||||
2. Find: "count": "42" (string instead of int)
|
||||
3. Edit: Change to "count": 42
|
||||
4. Bash: go test ./internal/parser
|
||||
5. Verify: Test passes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 8: String Exact Match
|
||||
|
||||
**Applicable to**: String Not Found (Edit Errors) (Category 13)
|
||||
|
||||
**Strategy**: Re-read file and copy exact string
|
||||
|
||||
**Steps**:
|
||||
1. **Re-read**: Read file to get current content
|
||||
2. **Locate**: Find target section (grep or visual)
|
||||
3. **Copy exact**: Copy current string exactly (no retyping)
|
||||
4. **Retry Edit**: Use exact old_string
|
||||
5. **Verify**: Edit succeeds
|
||||
|
||||
**Automation**: High (auto-refresh content before edit)
|
||||
|
||||
**Success Rate**: >95%
|
||||
|
||||
**Time to Recovery**: 1-3 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: String to replace not found in file
|
||||
|
||||
Recovery:
|
||||
1. Read internal/parser/parse.go # Fresh read
|
||||
2. Grep: Search for target function
|
||||
3. Copy exact string from current file
|
||||
4. Edit with exact old_string
|
||||
5. Verify: Edit succeeds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 9: MCP Server Health Check
|
||||
|
||||
**Applicable to**: MCP Server Errors (Category 9)
|
||||
|
||||
**Strategy**: Check server health, restart if needed
|
||||
|
||||
**Steps**:
|
||||
1. **Check status**: Verify MCP server is running
|
||||
2. **Test connection**: Simple query to test connectivity
|
||||
3. **Restart**: If down, restart MCP server
|
||||
4. **Optimize query**: If timeout, add pagination/filters
|
||||
5. **Retry**: Retry original query
|
||||
|
||||
**Automation**: Medium (health checks yes, query optimization no)
|
||||
|
||||
**Success Rate**: >80%
|
||||
|
||||
**Time to Recovery**: 2-10 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: MCP server connection failed
|
||||
|
||||
Recovery:
|
||||
1. Bash: ps aux | grep mcp-server
|
||||
2. If not running: Restart MCP server
|
||||
3. Test: Simple query (e.g., get_session_stats)
|
||||
4. If working: Retry original query
|
||||
5. Verify: Query succeeds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 10: Permission Fix
|
||||
|
||||
**Applicable to**: Permission Denied (Category 10)
|
||||
|
||||
**Strategy**: Change permissions or use appropriate user
|
||||
|
||||
**Steps**:
|
||||
1. **Check current**: `ls -la` to see permissions
|
||||
2. **Identify owner**: `ls -l` shows file owner
|
||||
3. **Fix permission**:
|
||||
- Option A: `chmod` to add permissions
|
||||
- Option B: `chown` to change owner
|
||||
- Option C: Use sudo (if appropriate)
|
||||
4. **Retry**: Retry original operation
|
||||
5. **Verify**: Operation succeeds
|
||||
|
||||
**Automation**: Low (security implications)
|
||||
|
||||
**Success Rate**: >90%
|
||||
|
||||
**Time to Recovery**: 1-3 minutes
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Error: Permission denied: /path/to/file
|
||||
|
||||
Recovery:
|
||||
1. Bash: ls -la /path/to/file
|
||||
2. See: -r--r--r-- (read-only)
|
||||
3. Bash: chmod u+w /path/to/file
|
||||
4. Retry: Write operation
|
||||
5. Verify: Success
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recovery Pattern Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
Error occurs
|
||||
├─ Build/compilation? → Pattern 1 (Fix-and-Retry)
|
||||
├─ Test failure? → Pattern 2 (Test Fixture Update)
|
||||
├─ File not found? → Pattern 3 (Path Correction) ⚠️ AUTOMATE
|
||||
├─ File too large? → Pattern 6 (Pagination) ⚠️ AUTOMATE
|
||||
├─ Write before read? → Pattern 4 (Read-Then-Write) ⚠️ AUTOMATE
|
||||
├─ Command not found? → Pattern 5 (Build-Then-Execute)
|
||||
├─ JSON parsing? → Pattern 7 (JSON Schema Fix)
|
||||
├─ String not found (Edit)? → Pattern 8 (String Exact Match)
|
||||
├─ MCP server? → Pattern 9 (MCP Health Check)
|
||||
├─ Permission denied? → Pattern 10 (Permission Fix)
|
||||
└─ Other? → Consult taxonomy for category
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automation Priority
|
||||
|
||||
**High Priority** (Full automation possible):
|
||||
1. Pattern 3: Path Correction (validate-path.sh)
|
||||
2. Pattern 4: Read-Then-Write (check-read-before-write.sh)
|
||||
3. Pattern 6: Pagination (check-file-size.sh)
|
||||
|
||||
**Medium Priority** (Partial automation):
|
||||
4. Pattern 5: Build-Then-Execute
|
||||
5. Pattern 7: JSON Schema Fix
|
||||
6. Pattern 9: MCP Server Health
|
||||
|
||||
**Low Priority** (Manual required):
|
||||
7. Pattern 1: Syntax Error Fix
|
||||
8. Pattern 2: Test Fixture Update
|
||||
9. Pattern 10: Permission Fix
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### General Recovery Workflow
|
||||
|
||||
1. **Classify**: Match error to category (use taxonomy.md)
|
||||
2. **Select pattern**: Choose appropriate recovery pattern
|
||||
3. **Execute steps**: Follow pattern steps systematically
|
||||
4. **Verify**: Confirm recovery successful
|
||||
5. **Document**: Note if pattern needs refinement
|
||||
|
||||
### Efficiency Tips
|
||||
|
||||
- Keep taxonomy.md open for quick classification
|
||||
- Use automation tools when available
|
||||
- Don't skip verification steps
|
||||
- Track recurring errors for prevention
|
||||
|
||||
### Common Mistakes
|
||||
|
||||
❌ **Don't**: Retry without understanding error
|
||||
❌ **Don't**: Skip verification step
|
||||
❌ **Don't**: Ignore automation opportunities
|
||||
✅ **Do**: Classify error first
|
||||
✅ **Do**: Follow pattern steps systematically
|
||||
✅ **Do**: Verify recovery completely
|
||||
|
||||
---
|
||||
|
||||
**Source**: Bootstrap-003 Error Recovery Methodology
|
||||
**Framework**: BAIME (Bootstrapped AI Methodology Engineering)
|
||||
**Status**: Production-ready, validated with 1336 errors
|
||||
Reference in New Issue
Block a user