image-auditor

# Image Auditor Skill

Non-destructive 4-phase image validation pipeline: Discover, Validate, Analyze, Report. Read and follow the repository CLAUDE.md before starting any audit.

```
/image-audit                    # Audit entire site
/image-audit content/posts/     # Audit specific directory
/image-audit --post my-post.md  # Audit single post
```

By default, every audit runs all check categories (alt text, existence, size, format, unused images) and calculates per-post page weight. Optional modes: **Deep Scan** includes theme images and `assets/` directory. **Auto-Optimize** generates optimized versions (requires imagemagick and explicit user consent). **Strict Mode** treats all suggestions as blockers.

---

## Instructions

### Phase 1: DISCOVER

**Goal**: Build a complete map of all images and all image references in the codebase.

**Step 1: Find all image files**

Use Glob to locate image files:
- Pattern: `static/**/*.{png,jpg,jpeg,gif,webp,svg}`
- Record each file's absolute path and size (use `ls -la` or `stat`) -- measure actual bytes, never estimate

**Step 2: Find all image references in content**

Use Grep to search content files for these patterns:
- Markdown images: `![alt](path)` -- regex: `!\[.*?\]\(.*?\)`
- Hugo figure shortcode: `{{< figure src="..." >}}` -- regex: `figure.*src=`
- HTML img tags: `<img src="..." alt="...">` -- regex: `<img.*src=`
- Raw path references: `.png)`, `.jpg)`, `.webp)`, `.svg)`

**Step 3: Build reference map**

For each image reference, record:
- Source file path (absolute)
- Line number
- Image path (as written in source)
- Resolved path (in static/)
- Alt text (if present)

**Path Resolution Rules:**
- `/images/foo.png` resolves to `static/images/foo.png`
- `images/foo.png` resolves to `static/images/foo.png`
- `../images/foo.png` resolves relative to the content file's location (always resolve from the content file's directory, never check the literal string against static/)
- Hugo shortcode `src=` values follow the same resolution rules

**Gate**: Reference map is complete with all images and all references catalogued. Proceed only when gate passes.

### Phase 2: VALIDATE

**Goal**: Check every reference and every image against quality criteria. Verify every reported issue by reading the actual file or reference before recording it -- never report an issue based on assumption alone.

**Step 1: Alt text validation**

| Status | Condition |
|--------|-----------|
| PASS | Alt text present, descriptive, 10-125 characters |
| WARN | Alt text too generic (single words: "image", "screenshot", "picture", "photo", "diagram", "figure", "img") -- always check against this generic term list rather than subjectively judging quality |
| FAIL | Alt text missing or empty |

15% of users rely on assistive technology, so validate all alt text regardless of perceived importance.

See `references/alt-text-examples.md` for detailed quality guidelines.

**Step 2: File existence validation**

| Status | Condition |
|--------|-----------|
| PASS | Image file exists at resolved path |
| FAIL | Image file not found at resolved path |

**Step 3: File size validation**

| Status | Threshold |
|--------|-----------|
| PASS | <200KB |
| WARN | 200KB-500KB |
| FAIL | >500KB |

See `references/size-guidelines.md` for type-specific thresholds.

**Step 4: Format appropriateness**

| Image Type | Preferred Format | Detection Heuristic |
|------------|------------------|---------------------|
| Photos | WebP, JPEG | Filename: "photo", "hero", "banner" |
| Screenshots | WebP, PNG | Filename: "screenshot", "screen-", "capture" |
| Diagrams | SVG, WebP | Filename: "diagram", "chart", "graph", "flow" |
| Icons/Logos | SVG | Filename: "icon", "logo", "favicon" |

Report format savings estimates and let the user decide whether to convert -- do not skip format recommendations on the assumption they are unnecessary.

See `references/format-selection.md` for the complete decision flowchart.

**Step 5: Unused image detection**

Compare all files in static/images/ against the reference map. Any file with zero references is reported as unused. Always perform this step -- unused images bloat the repository and deployment size.

**Gate**: All references validated against all criteria. Every issue has a severity level, file path, and line number. Proceed only when gate passes.

### Phase 3: ANALYZE

**Goal**: Compute aggregate metrics and optimization potential.

**Step 1: Page weight per post**

For each post containing images, sum total image bytes and count images.

| Status | Total Images |
|--------|--------------|
| Good | <1 MB |
| Warn | 1-3 MB |
| Critical | >3 MB |

**Step 2: Optimization estimates**

Calculate potential savings for each actionable item:
- WebP conversion: ~30% for photos, ~25% for screenshots
- Resize to max 1200px width: varies by original dimensions
- Compression optimization: ~10-20% additional savings
- Total estimated savings across all recommendations

Present estimates as concrete byte counts (e.g., "save ~340 KB"), never as vague percentages alone.

**Step 3: Identify highest-impact fixes**

Rank issues by potential impact:
1. Broken references (FAIL) -- content is visibly broken
2. Missing alt text (FAIL) -- accessibility violation
3. Oversized images on heavy pages -- worst page weight first
4. Format mismatches with largest savings potential

**Gate**: Metrics computed for all posts. Optimization estimates are concrete numbers. Priority ranking established. Proceed only when gate passes.

### Phase 4: REPORT

**Goal**: Generate a structured, actionable audit report. This phase is read-only -- never modify, resize, convert, or delete images. Report findings and recommendations only; changes require explicit user request.

Follow the report format in `references/report-templates.md`. The report must include:

1. **Summary**: Total images, total size, posts with images, averages
2. **Alt Text Issues**: Every FAIL and WARN with file path, line number, current alt text
3. **File Size Issues**: Every oversized image with size and recommendation
4. **Missing Files**: Every broken reference with source file and line number
5. **Unused Images**: Every orphaned file with size
6. **Format Suggestions**: Aggregated conversion recommendations with estimated savings
7. **Page Weight**: Per-post breakdown, heaviest posts first
8. **Recommendations**: Numbered, prioritized action items
9. **Status Line**: PASS, WARN, or FAIL with counts

Every issue in the report must include an absolute file path and line number so the user can locate and fix it. Clearly distinguish severity levels: FAIL (broken, must fix), WARN (should fix), INFO (suggestion). Do not conflate severity -- a format suggestion is not a blocker.

**Gate**: Report is complete with all sections populated. Every issue is actionable (file path + line number + recommendation). Report ends with a status line.

---

## Examples

### Example 1: Clean Site
User says: "Run an image audit"
Actions:
1. Glob for all images in static/, Grep for all references in content/ (DISCOVER)
2. Validate alt text, existence, sizes, formats for each reference (VALIDATE)
3. Compute page weights and optimization potential (ANALYZE)
4. Generate report showing no critical issues, minor format suggestions (REPORT)
Result: STATUS: PASS with optional WebP conversion suggestions

### Example 2: Site with Multiple Issues
User says: "Check all images before we publish"
Actions:
1. Build reference map of 24 images across 8 posts (DISCOVER)
2. Find 2 missing alt texts, 1 broken reference, 1 oversized image (VALIDATE)
3. Calculate 4.2 MB total weight, 2.1 MB on heaviest post (ANALYZE)
4. Generate report with 4 critical issues and 5 format suggestions (REPORT)
Result: STATUS: FAIL with prioritized fix list

### Example 3: Single Post Audit
User says: "Audit images in content/posts/2024-12-theme.md"
Actions:
1. Grep that specific file for image references (DISCOVER)
2. Validate the 4 images found: 3 pass, 1 missing alt text (VALIDATE)
3. Sum 890 KB total weight for this post (ANALYZE)
4. Generate focused report for single post (REPORT)
Result: 1 issue to fix (missing alt text on line 45)

---

## Error Handling

### Error: "No Images Found"
Cause: Wrong directory, no content files, or non-standard image paths
Solution:
1. Verify static/images/ directory exists
2. Confirm content files use standard image reference patterns
3. Check for custom Hugo shortcodes that reference images differently

### Error: "Cannot Determine Image Dimensions"
Cause: imagemagick not installed or file permissions issue
Solution:
1. Skip dimension checks and audit only file size
2. Report that dimension analysis was skipped
3. Note that `identify` command requires imagemagick package

### Error: "Path Resolution Ambiguous"
Cause: Relative paths in content that could resolve to multiple locations
Solution:
1. Try resolving relative to the content file's directory first
2. Fall back to resolving relative to static/
3. Report both possible resolutions if ambiguous

### Error: "Permission Denied Reading Files"
Cause: File permissions prevent reading image files or content directories
Solution:
1. Check file permissions with `ls -la` on the failing path
2. Report which files are inaccessible and skip them
3. Note skipped files in the report summary so the user knows the audit is incomplete

---

## References

### Integration Notes

**With pre-publish-checker**: The pre-publish-checker skill performs basic image validation (existence, alt text presence). This skill provides deeper analysis including format optimization, page weight, and unused image detection. Use pre-publish for quick pass/fail; use image-auditor for comprehensive audits.

**With Hugo build**: Run image audit before `hugo --minify` to catch broken references and optimize assets before deployment.

**Recommended cadence**: Run full audit periodically (weekly or before releases). Address FAIL issues immediately. Schedule WARN issues for optimization sprints.

### Reference Files
- `${CLAUDE_SKILL_DIR}/references/alt-text-examples.md`: Good and bad alt text examples by image type
- `${CLAUDE_SKILL_DIR}/references/size-guidelines.md`: Maximum file sizes, dimension limits, page weight budgets
- `${CLAUDE_SKILL_DIR}/references/format-selection.md`: Format decision flowchart and detection heuristics
- `${CLAUDE_SKILL_DIR}/references/report-templates.md`: Full audit and single-post report templates