gh-yaleh-meta-cc-claude/skills/error-recovery/examples/file-operation-errors.md

File Operation Errors Example

Project: meta-cc Development Error Categories: File Not Found (Category 3), Write Before Read (Category 5), File Size (Category 4) Initial Errors: 404 file-related errors (30.2% of total) Final Errors: 87 after automation (6.5%) Reduction: 78.5% through automation

This example demonstrates comprehensive file operation error handling with automation.

---

Initial Problem

File operation errors were the largest error category:

• 250 File Not Found errors (18.7%)
• 84 File Size Exceeded errors (6.3%)
• 70 Write Before Read errors (5.2%)

Common scenarios:

1. Typos in file paths → hours wasted debugging
2. Large files crashing Read tool → session lost
3. Forgetting to Read before Edit → workflow interrupted

---

Solution 1: Path Validation Automation

The Problem

Error: File does not exist: /home/yale/work/meta-cc/internal/testutil/fixture.go

Actual file: fixtures.go (plural)

Time wasted: 5-10 minutes per error × 250 errors = 20-40 hours total

Automation Script

Created: scripts/validate-path.sh

#!/bin/bash
# Usage: validate-path.sh <path>

path="$1"

# Check if file exists
if [ -f "$path" ]; then
    echo "✓ File exists: $path"
    exit 0
fi

# File doesn't exist, try to find similar files
dir=$(dirname "$path")
filename=$(basename "$path")

echo "✗ File not found: $path"
echo ""
echo "Searching for similar files..."

# Find files with similar names (fuzzy matching)
find "$dir" -maxdepth 1 -type f -iname "*${filename:0:5}*" 2>/dev/null | while read -r similar; do
    echo "  Did you mean: $similar"
done

# Check if directory exists
if [ ! -d "$dir" ]; then
    echo ""
    echo "Note: Directory doesn't exist: $dir"
    echo "  Check if path is correct"
fi

exit 1

Usage Example

Before automation:

# Manual debugging
$ wc -l /path/internal/testutil/fixture.go
wc: /path/internal/testutil/fixture.go: No such file or directory

# Try to find it manually
$ ls /path/internal/testutil/
$ find . -name "*fixture*"
# ... 5 minutes later, found: fixtures.go

With automation:

$ ./scripts/validate-path.sh /path/internal/testutil/fixture.go
✗ File not found: /path/internal/testutil/fixture.go

Searching for similar files...
  Did you mean: /path/internal/testutil/fixtures.go
  Did you mean: /path/internal/testutil/fixture_test.go

# Immediately see the correct path!
$ wc -l /path/internal/testutil/fixtures.go
42 /path/internal/testutil/fixtures.go

Results

Impact:

• Prevented: 163/250 errors (65.2%)
• Time saved per error: 5 minutes
• Total time saved: 13.5 hours

Why not 100%?:

• 87 errors were files that truly didn't exist yet (workflow order issues)
• These needed different fix (create file first, or reorder operations)

---

Solution 2: File Size Check Automation

The Problem

Error: File content (46892 tokens) exceeds maximum allowed tokens (25000)

Result: Session lost, context reset, frustrating experience

Frequency: 84 errors (6.3%)

Automation Script

Created: scripts/check-file-size.sh

#!/bin/bash
# Usage: check-file-size.sh <file>

file="$1"
max_tokens=25000

# Check file exists
if [ ! -f "$file" ]; then
    echo "✗ File not found: $file"
    exit 1
fi

# Estimate tokens (rough: 1 line ≈ 10 tokens)
lines=$(wc -l < "$file")
estimated_tokens=$((lines * 10))

echo "File: $file"
echo "Lines: $lines"
echo "Estimated tokens: ~$estimated_tokens"

if [ $estimated_tokens -lt $max_tokens ]; then
    echo "✓ Safe to read (under $max_tokens token limit)"
    exit 0
else
    echo "⚠ File too large for single read!"
    echo ""
    echo "Options:"
    echo "  1. Use pagination:"
    echo "     Read $file offset=0 limit=1000"
    echo ""
    echo "  2. Use grep to extract:"
    echo "     grep \"pattern\" $file"
    echo ""
    echo "  3. Use head/tail:"
    echo "     head -n 1000 $file"
    echo "     tail -n 1000 $file"

    # Calculate suggested chunk size
    chunks=$((estimated_tokens / max_tokens + 1))
    lines_per_chunk=$((lines / chunks))
    echo ""
    echo "  Suggested chunks: $chunks"
    echo "  Lines per chunk: ~$lines_per_chunk"

    exit 1
fi

Usage Example

Before automation:

# Try to read large file
$ Read large-session.jsonl
Error: File content (46892 tokens) exceeds maximum allowed tokens (25000)

# Session lost, context reset
# Start over with pagination...

With automation:

$ ./scripts/check-file-size.sh large-session.jsonl
File: large-session.jsonl
Lines: 12000
Estimated tokens: ~120000

⚠ File too large for single read!

Options:
  1. Use pagination:
     Read large-session.jsonl offset=0 limit=1000

  2. Use grep to extract:
     grep "pattern" large-session.jsonl

  3. Use head/tail:
     head -n 1000 large-session.jsonl

  Suggested chunks: 5
  Lines per chunk: ~2400

# Use suggestion
$ Read large-session.jsonl offset=0 limit=2400
✓ Successfully read first chunk

Results

Impact:

• Prevented: 84/84 errors (100%)
• Time saved per error: 10 minutes (including context restoration)
• Total time saved: 14 hours

---

Solution 3: Read-Before-Write Check

The Problem

Error: File has not been read yet. Read it first before writing to it.

Cause: Forgot to Read file before Edit operation

Frequency: 70 errors (5.2%)

Automation Script

Created: scripts/check-read-before-write.sh

#!/bin/bash
# Usage: check-read-before-write.sh <file> <operation>
# operation: edit|write

file="$1"
operation="${2:-edit}"

# Check if file exists
if [ ! -f "$file" ]; then
    if [ "$operation" = "write" ]; then
        echo "✓ New file, Write is OK: $file"
        exit 0
    else
        echo "✗ File doesn't exist, can't Edit: $file"
        echo "  Use Write for new files, or create file first"
        exit 1
    fi
fi

# File exists, check if this is a modification
if [ "$operation" = "edit" ]; then
    echo "⚠ Existing file, need to Read before Edit!"
    echo ""
    echo "Workflow:"
    echo "  1. Read $file"
    echo "  2. Edit $file old_string=\"...\" new_string=\"...\""
    exit 1
elif [ "$operation" = "write" ]; then
    echo "⚠ Existing file, need to Read before Write!"
    echo ""
    echo "Workflow for modifications:"
    echo "  1. Read $file"
    echo "  2. Edit $file old_string=\"...\" new_string=\"...\""
    echo ""
    echo "Or for complete rewrite:"
    echo "  1. Read $file  (to see current content)"
    echo "  2. Write $file <new_content>"
    exit 1
fi

Usage Example

Before automation:

# Forget to read, try to edit
$ Edit internal/parser/parse.go old_string="x" new_string="y"
Error: File has not been read yet.

# Retry with Read
$ Read internal/parser/parse.go
$ Edit internal/parser/parse.go old_string="x" new_string="y"
✓ Success

With automation:

$ ./scripts/check-read-before-write.sh internal/parser/parse.go edit
⚠ Existing file, need to Read before Edit!

Workflow:
  1. Read internal/parser/parse.go
  2. Edit internal/parser/parse.go old_string="..." new_string="..."

# Follow workflow
$ Read internal/parser/parse.go
$ Edit internal/parser/parse.go old_string="x" new_string="y"
✓ Success

Results

Impact:

• Prevented: 70/70 errors (100%)
• Time saved per error: 2 minutes
• Total time saved: 2.3 hours

---

Combined Impact

Error Reduction

Category	Before	After	Reduction
File Not Found	250 (18.7%)	87 (6.5%)	65.2%
File Size	84 (6.3%)	0 (0%)	100%
Write Before Read	70 (5.2%)	0 (0%)	100%
Total	404 (30.2%)	87 (6.5%)	78.5%

Time Savings

Category	Errors Prevented	Time per Error	Total Saved
File Not Found	163	5 min	13.5 hours
File Size	84	10 min	14 hours
Write Before Read	70	2 min	2.3 hours
Total	317	Avg 6.2 min	29.8 hours

ROI

Setup cost: 3 hours (script development + testing) Maintenance: 15 minutes/week Time saved: 29.8 hours (first month)

ROI: 9.9x in first month

---

Integration with Workflow

Pre-Command Hooks

# .claude/hooks/pre-tool-use.sh
#!/bin/bash

tool="$1"
shift
args="$@"

case "$tool" in
    Read)
        file="$1"
        ./scripts/check-file-size.sh "$file" || exit 1
        ./scripts/validate-path.sh "$file" || exit 1
        ;;
    Edit|Write)
        file="$1"
        ./scripts/check-read-before-write.sh "$file" "${tool,,}" || exit 1
        ./scripts/validate-path.sh "$file" || exit 1
        ;;
esac

exit 0

Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Check for script updates
if git diff --cached --name-only | grep -q "scripts/"; then
    echo "Testing automation scripts..."
    bash -n scripts/*.sh || exit 1
fi

---

Key Learnings

1. Automation ROI is Immediate

Time investment: 3 hours Time saved: 29.8 hours (first month) ROI: 9.9x

2. Fuzzy Matching is Powerful

Path suggestions saved:

• 163 file-not-found errors
• Average 5 minutes per error
• 13.5 hours total

3. Proactive > Reactive

File size check prevented:

• 84 session interruptions
• Context loss prevention
• Better user experience

4. Simple Scripts, Big Impact

All scripts <50 lines:

• Easy to understand
• Easy to maintain
• Easy to modify

5. Error Prevention > Error Recovery

Error recovery: 5-10 minutes per error Error prevention: <1 second per operation

Prevention is 300-600x faster

---

Reusable Patterns

Pattern 1: Pre-Operation Validation

# Before any file operation
validate_preconditions() {
    local file="$1"
    local operation="$2"

    # Check 1: Path exists or is valid
    validate_path "$file" || return 1

    # Check 2: Size is acceptable
    check_size "$file" || return 1

    # Check 3: Permissions are correct
    check_permissions "$file" "$operation" || return 1

    return 0
}

Pattern 2: Fuzzy Matching

# Find similar paths
find_similar() {
    local search="$1"
    local dir=$(dirname "$search")
    local base=$(basename "$search")

    # Try case-insensitive
    find "$dir" -maxdepth 1 -iname "$base" 2>/dev/null

    # Try partial match
    find "$dir" -maxdepth 1 -iname "*${base:0:5}*" 2>/dev/null
}

Pattern 3: Helpful Error Messages

# Don't just say "error"
echo "✗ File not found: $path"
echo ""
echo "Suggestions:"
find_similar "$path" | while read -r match; do
    echo "  - $match"
done
echo ""
echo "Or check if:"
echo "  1. Path is correct"
echo "  2. File needs to be created first"
echo "  3. You're in the right directory"

---

Transfer to Other Projects

These scripts work for:

• Any project using Claude Code
• Any project with file operations
• Any CLI tool development

Adaptation needed:

• Token limits (adjust for your system)
• Path patterns (adjust find commands)
• Integration points (hooks, CI/CD)

Core principles remain:

1. Validate before executing
2. Provide fuzzy matching
3. Give helpful error messages
4. Automate common checks

---

Source: Bootstrap-003 Error Recovery Methodology Framework: BAIME (Bootstrapped AI Methodology Engineering) Status: Production-ready, 78.5% error reduction, 9.9x ROI