Add scan flow MVP and local Axiom skill workspace
This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
This commit is contained in:
Matthias
294
.claude/skills/axiom-audit-storage/SKILL.md
Normal file
294
.claude/skills/axiom-audit-storage/SKILL.md
Normal file
@@ -0,0 +1,294 @@
|
||||
---
|
||||
name: axiom-audit-storage
|
||||
description: Use when the user mentions file storage issues, data loss, backup bloat, or asks to audit storage usage.
|
||||
license: MIT
|
||||
disable-model-invocation: 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/**:
|
||||
```bash
|
||||
# Look for tmp/ path usage
|
||||
tmp/|NSTemporaryDirectory
|
||||
```
|
||||
|
||||
**Large Files Without Backup Exclusion**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# File writes without protection specification
|
||||
\.write\(to:|Data\(contentsOf:|FileManager.*createFile
|
||||
```
|
||||
|
||||
Then check if .completeFileProtection or FileProtectionType is specified.
|
||||
|
||||
**Wrong Storage Locations**:
|
||||
```bash
|
||||
# Check for hardcoded paths (should use FileManager URLs)
|
||||
/Documents/|/Library/|/tmp/
|
||||
```
|
||||
|
||||
**UserDefaults Abuse**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
```swift
|
||||
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:
|
||||
```swift
|
||||
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:
|
||||
```swift
|
||||
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:
|
||||
```swift
|
||||
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]
|
||||
```
|
||||
Reference in New Issue
Block a user