Smart File WriterSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Error writing file: results/model_checkpoint.pth

Diagnosis: Parent directory 'results' does not exist
Resolution: Created directory 'results'
Retry: Write succeeded

Error: Path too long (285 characters)

Warning: Path length 285 chars exceeds Windows limit (260)
Alternative: D:\project\a3f5e8b2c1d4.csv
Mapping saved to: path_mappings.json
Write succeeded to alternative path

PermissionError: [Errno 13] Permission denied: 'data.csv'

Diagnosis: File 'data.csv' has read-only attribute
Resolution: Run 'attrib -r data.csv' to remove read-only flag
[After confirmation] Attribute removed. Retry succeeded.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: smart-file-writer
description: "Intelligent file write error handler: diagnoses permissions, disk space, path length, file locks before retrying. Use when you encounter 'Error writing file', 'Permission denied', 'Access denied', 'No space left', or related file write failures."
---

# smart-file-writer Skill

Automatically diagnoses and resolves file write errors through systematic investigation rather than blind retries. Prevents common write failures proactively.

## When to Use This Skill

Use this skill when any of these occurs:
- "Error writing file" messages
- "Permission denied" or "Access denied" errors
- "No space left on device" errors
- "File exists" conflicts
- "Path too long" errors (Windows)
- "Read-only file system" errors
- Any file write operation failure (Python, CLI, any language)
- Before critical file writes (proactive mode)

## Not For / Boundaries

This skill does NOT:
- Handle network file system issues (NFS, SMB) beyond basic diagnostics
- Modify system-level permissions without user confirmation
- Bypass security policies or antivirus software
- Handle database write operations (different error domain)

Required inputs:
- Target file path
- Intended operation (write, append, create, etc.)
- Error message (if reactive mode)

## Quick Reference

### Diagnostic Checklist (Run Before Retry)

**1. Path Validation**
```python
import os
# Check path length (Windows: 260 char limit)
if len(filepath) > 260 and os.name == 'nt':
    print(f"Path too long: {len(filepath)} chars")

# Check parent directory exists
parent = os.path.dirname(filepath)
if not os.path.exists(parent):
    print(f"Parent directory missing: {parent}")
```

**2. Permission Check**
```python
import os
# Check directory write permission
parent = os.path.dirname(filepath) or '.'
if not os.access(parent, os.W_OK):
    print(f"No write permission: {parent}")

# Check file permissions if exists
if os.path.exists(filepath):
    if not os.access(filepath, os.W_OK):
        print(f"File not writable: {filepath}")
```

**3. Disk Space Check**
```python
import shutil
# Check available disk space
stat = shutil.disk_usage(os.path.dirname(filepath) or '.')
free_gb = stat.free / (1024**3)
if free_gb < 0.1:  # Less than 100MB
    print(f"Low disk space: {free_gb:.2f} GB free")
```

**4. File Lock Detection**
```python
import os
# Try to open with exclusive access
try:
    with open(filepath, 'a') as f:
        pass
except PermissionError:
    print(f"File locked by another process: {filepath}")
```

**5. Windows-Specific Checks**
```bash
# Check if file is in use (Windows)
handle.exe -a "filepath"

# Check file attributes
attrib "filepath"
```

### Resolution Patterns

**Pattern 1: Create Missing Directories**
```python
import os
os.makedirs(os.path.dirname(filepath), exist_ok=True)
```

**Pattern 2: Atomic Write (Temp + Rename)**
```python
import os
import tempfile

# Write to temp file first
temp_fd, temp_path = tempfile.mkstemp(dir=os.path.dirname(filepath))
try:
    with os.fdopen(temp_fd, 'w') as f:
        f.write(content)
    # Atomic rename
    os.replace(temp_path, filepath)
except Exception as e:
    os.unlink(temp_path)
    raise
```

**Pattern 3: Exponential Backoff for Transient Issues**
```python
import time

def write_with_retry(filepath, content, max_retries=3):
    for attempt in range(max_retries):
        try:
            with open(filepath, 'w') as f:
                f.write(content)
            return True
        except (PermissionError, OSError) as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(wait)
            else:
                raise
```

**Pattern 4: Alternative Path (Shorten Long Paths)**
```python
import os
import hashlib

def shorten_path(long_path):
    """Use hash for long filenames"""
    dir_path = os.path.dirname(long_path)
    filename = os.path.basename(long_path)

    if len(long_path) > 260:
        # Hash the filename
        name, ext = os.path.splitext(filename)
        hash_name = hashlib.md5(name.encode()).hexdigest()[:16]
        return os.path.join(dir_path, f"{hash_name}{ext}")
    return long_path
```

**Pattern 5: Permission Fix Suggestions**
```bash
# Linux/Mac: Add write permission
chmod u+w filepath

# Windows: Remove read-only attribute
attrib -r filepath

# Windows: Take ownership (admin required)
takeown /f filepath
icacls filepath /grant %username%:F
```

**Pattern 6: Detect Antivirus Interference**
```python
import time
import os

def is_antivirus_blocking(filepath):
    """Detect if antivirus is scanning file"""
    try:
        # Try to open exclusively
        with open(filepath, 'r+b') as f:
            pass
        return False
    except PermissionError:
        # Wait and retry
        time.sleep(0.5)
        try:
            with open(filepath, 'r+b') as f:
                pass
            return True  # Was temporarily blocked
        except:
            return False  # Persistent block
```

### Proactive Pre-Write Validation

**Before Any Critical Write**
```python
def validate_write_conditions(filepath):
    """Run before writing important files"""
    issues = []

    # 1. Path length
    if len(filepath) > 260 and os.name == 'nt':
        issues.append(f"Path too long: {len(filepath)} chars")

    # 2. Parent directory
    parent = os.path.dirname(filepath) or '.'
    if not os.path.exists(parent):
        issues.append(f"Parent missing: {parent}")
    elif not os.access(parent, os.W_OK):
        issues.append(f"No write permission: {parent}")

    # 3. Disk space
    stat = shutil.disk_usage(parent)
    if stat.free < 100 * 1024 * 1024:  # 100MB
        issues.append(f"Low disk space: {stat.free / 1024**2:.1f} MB")

    # 4. File exists and writable
    if os.path.exists(filepath):
        if not os.access(filepath, os.W_OK):
            issues.append(f"File not writable: {filepath}")

    return issues
```

### Integration with Claude Code Tools

**Wrap Write 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.