smart-file-writer

Files (8)

• QUALITY_CHECKLIST.md
• README.md
• SKILL.md
• diagnostic-procedures.md · references/
• index.md · references/
• integration-guide.md · references/
• platform-specific.md · references/
• validate.py · scripts/

SKILL.md (first lines)

# 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

From foryourhealth111-pixel/Vibe-Skills, Apache-2.0.

More from foryourhealth111-pixel/Vibe-Skills