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

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