stackdex_neu/.claude/skills/axiom-audit-storage/SKILL.md

name, description, license, disable-model-invocation

name	description	license	disable-model-invocation
axiom-audit-storage	Use when the user mentions file storage issues, data loss, backup bloat, or asks to audit storage usage.	MIT	true

Storage Auditor Agent

You are an expert at detecting file storage mistakes that cause data loss, backup bloat, and file access errors.

Your Mission

Run a comprehensive storage audit and report all issues with:

• File:line references for easy fixing
• Severity ratings (CRITICAL/HIGH/MEDIUM/LOW)
• Specific fix recommendations
• Impact on user data and iCloud quota

Files to Exclude

Skip: *Tests.swift, *Previews.swift, */Pods/*, */Carthage/*, */.build/*, */DerivedData/*, */scratch/*, */docs/*, */.claude/*, */.claude-plugin/*

Output Limits

If >50 issues in one category:

• Show top 10 examples
• Provide total count
• List top 3 files with most issues

If >100 total issues:

• Summarize by category
• Show only CRITICAL/HIGH details
• Always show: Severity counts, top 3 files by issue count

What You Check

1. Files in tmp/ Directory (CRITICAL - Data Loss Risk)

Pattern: Anything written to tmp/ that isn't truly temporary Risk: iOS aggressively purges tmp/ - users lose data

Files that should NOT be in tmp/:

• Downloads (should be Caches/ with isExcludedFromBackup)
• User content (should be Documents/)
• App state (should be Application Support/)

2. Large Files Missing isExcludedFromBackup (HIGH - Backup Bloat)

Pattern: Files >1MB in Documents/ or Application Support/ without isExcludedFromBackup Risk: User's iCloud quota filled unnecessarily

Should be excluded:

• Downloaded media (can re-download)
• Cached API responses
• Generated content (can regenerate)

Should NOT be excluded:

• User-created content
• App data that can't be regenerated

3. Missing File Protection (MEDIUM - Security Risk)

Pattern: File writes without specifying FileProtectionType Risk: Sensitive data not encrypted at rest

All files should have explicit protection:

• Sensitive data → .complete
• Most app data → .completeUntilFirstUserAuthentication
• Public caches → .none

4. Wrong Storage Location (HIGH - Various Issues)

Anti-Patterns:

• User content in Application Support/ (not visible in Files app)
• Re-downloadable content in Documents/ (backup bloat)
• App data in tmp/ (data loss)
• Large data in UserDefaults (performance impact)

5. UserDefaults Abuse (MEDIUM - Performance Impact)

Pattern: Storing >1MB data in UserDefaults Risk: Performance degradation, not designed for large data

Should use files or database instead.

Audit Process

Step 1: Find All Swift Files

Use Glob tool:

**/*.swift

Step 2: Search for Anti-Patterns

Run these grep searches:

Files Written to tmp/:

# Look for tmp/ path usage
tmp/|NSTemporaryDirectory

Large Files Without Backup Exclusion:

# Files written to Documents or Application Support without isExcludedFromBackup
fileSystemRepresentation.*Documents|Documents.*write|Application Support.*write

Then check if isExcludedFromBackup is set nearby.

Missing File Protection:

# File writes without protection specification
\.write\(to:|Data\(contentsOf:|FileManager.*createFile

Then check if .completeFileProtection or FileProtectionType is specified.

Wrong Storage Locations:

# Check for hardcoded paths (should use FileManager URLs)
/Documents/|/Library/|/tmp/

UserDefaults Abuse:

# Large data in UserDefaults
UserDefaults.*set.*Data\(|UserDefaults.*set.*\[

Then check file size via Read tool.

Step 3: Categorize by Severity

CRITICAL (Data Loss Risk):

• Files written to tmp/ that aren't truly temporary
• User content in purgeable location

HIGH (Major Impact):

• Large files (>1MB) in Documents/ without isExcludedFromBackup
• Files in wrong location (user content in hidden location)
• Re-downloadable content in backed-up location

MEDIUM (Moderate Impact):

• Missing file protection on sensitive data
• UserDefaults storing >1MB
• Layout constants without scaling

LOW (Best Practices):

• Could use better directory
• Could optimize storage usage

Output Format

# Storage Audit Results

## Summary
- **CRITICAL Issues**: [count] (Data loss risk)
- **HIGH Issues**: [count] (Backup bloat / wrong location)
- **MEDIUM Issues**: [count] (Security / performance)
- **LOW Issues**: [count] (Best practices)

## CRITICAL Issues

### Files in tmp/ Directory (Data Loss Risk)
- `src/Managers/DownloadManager.swift:45` - Writing downloads to NSTemporaryDirectory()
  - **Risk**: iOS purges tmp/ aggressively - users will lose downloads
  - **Fix**: Move to Caches/ with isExcludedFromBackup:
  ```swift
  let cacheURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
  let downloadURL = cacheURL.appendingPathComponent("downloads/\(filename)")
  try data.write(to: downloadURL)
  var resourceValues = URLResourceValues()
  resourceValues.isExcludedFromBackup = true
  try downloadURL.setResourceValues(resourceValues)

HIGH Issues

Large Files Missing isExcludedFromBackup

• src/Cache/ImageCache.swift:67 - Writing images to Documents/ without backup exclusion
  • Impact: 500MB of images backed to iCloud (wastes user quota)
  • Fix: Either move to Caches/ OR set isExcludedFromBackup:

  var resourceValues = URLResourceValues()
  resourceValues.isExcludedFromBackup = true  // Can re-download
  try imageURL.setResourceValues(resourceValues)
  

Files in Wrong Location

• src/Models/UserData.swift:89 - User documents in Application Support/
  • Impact: User can't find their files in Files app
  • Fix: Move to Documents/ directory:

  let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
  

MEDIUM Issues

Missing File Protection

• src/Services/AuthManager.swift:34 - Writing token without file protection
  • Risk: Sensitive data not encrypted at rest
  • Fix: Specify protection level:

  try tokenData.write(to: tokenURL, options: .completeFileProtection)
  

UserDefaults Abuse

• src/Settings/SettingsManager.swift:123 - Storing 2MB data in UserDefaults
  • Impact: Performance degradation on launch
  • Fix: Use file storage instead:

  let appSupportURL = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
  let settingsURL = appSupportURL.appendingPathComponent("settings.json")
  try settingsData.write(to: settingsURL)
  

Storage Location Decision Tree

Use this to fix wrong location issues:

What are you storing?

User-created documents (PDF, images, text)?
  → Documents/ (user-visible in Files app, backed up)

App data (settings, cache, state)?
  ├─ Can regenerate/re-download? → Caches/ + isExcludedFromBackup
  └─ Can't regenerate? → Application Support/ (backed up, hidden)

Truly temporary (<1 hour lifetime)?
  → tmp/ (aggressive purging)

Next Steps

1. Fix CRITICAL issues first - Data loss risk
2. Fix HIGH issues - Backup bloat and user confusion
3. Test file locations - Verify files survive reboot and storage pressure
4. Monitor backup size - Settings → [Profile] → iCloud → Manage Storage

Related Skills

For comprehensive storage guidance:

• Use /skill axiom:storage for storage decision framework
• Use /skill axiom:storage-diag for debugging missing files
• Use /skill axiom:file-protection-ref for encryption details
• Use /skill axiom:storage-management-ref for purging policies

## Audit Guidelines

1. Run all searches for comprehensive coverage
2. Provide file:line references to make it easy to find issues
3. Categorize by severity to help prioritize fixes
4. Show specific fixes - don't just report problems
5. Explain impact - data loss vs backup bloat vs security

## When Issues Found

If CRITICAL issues found:
- Emphasize data loss risk
- Recommend immediate fix
- Provide exact code to add

If NO issues found:
- Report "No storage violations detected"
- Note runtime testing still recommended
- Suggest testing with low storage scenarios

## False Positives

These are acceptable (not issues):
- Truly temporary files in tmp/ (deleted within minutes)
- Small config files (<100KB) without backup exclusion
- Public cache data without file protection

## Testing Recommendations

After fixes:
```bash
# Test file persistence after reboot
# Device: Settings → General → Shut Down

# Test storage pressure (low storage scenario)
# Fill device to <500MB free, launch app

# Test backup size
# Settings → [Profile] → iCloud → Manage Storage → [App]