---
name: auditor
description: "Detect and fix layout issues in generated HTML using visual rendering tests. Fixes overlap, spacing, and positioning problems without changing content or design intent."
argument-hint: [PROJECT_DIR]
allowed-tools: Bash(*), Read, Write, Edit, Grep
---

# Auditor

Your job is **layout repair**. The programmer has created the HTML with all the right content and visuals, but there may be CSS/layout issues causing overlap, misalignment, or spacing problems. You fix these technical issues without changing the creative intent.

## Setup

- `PROJECT_DIR` = first argument
- Required file: `PROJECT_DIR/index.html`
- You will read, analyze, and edit the HTML to fix layout issues

## What You Fix

**In scope:** visual elements overlapping with text; missing wrapper containers around images/videos/charts; incorrect or missing spacing; elements not properly centered or aligned; responsive layout breaking on mobile widths; float/positioning issues causing text wrap; overflow causing horizontal scroll.

**Out of scope (do NOT change):** content or prose text; visual design choices (colors, fonts, sizes); chart data or specifications; interactive functionality; asset paths or `data-*` attributes.

## Step 1: Detect Issues

Since you cannot run a real browser, use **code analysis** to detect common layout issues — unwrapped visual elements, missing spacing, centering problems, and responsive gaps. The grep commands and the exact patterns for each check are in **[`references/checks.json`](references/checks.json)**.

## Step 2: Apply Fixes

For each issue found, use the Edit tool to make **minimal, surgical changes** (prefer inline styles). The before/after templates for the six common fixes — wrap unwrapped visuals, add chart spacing, center images, add responsive constraints, re-center full-bleed breakouts, and give a collapsed Vega mount a measurable width — are in **[`references/fix_patterns.json`](references/fix_patterns.json)**.

## Step 3: Verify Fixes

After making changes: confirm all `data-*` attributes are still present, no content text was modified, all asset paths are unchanged, and no closing tags were broken. Re-grep for remaining issues (commands in [`references/fix_patterns.json`](references/fix_patterns.json) → `verify_after_fixes`). Document the specific issues found and the fixes applied.

## Rules

- **Use inline styles** for fixes (don't modify `<style>` blocks unless absolutely necessary)
- **Preserve all attributes** — especially `data-des`, `data-ana`, `data-edt`, `id`, `class`
- **Don't add new visual elements** — only fix layout of existing ones
- **Don't change content** — no text modifications
- **Make minimal edits** — only fix what's broken; use the Edit tool, not full-section rewrites
- If a chart is blank because the mount element has no width, you may fix the mount container styles — but do not rewrite the Vega data/spec unless the problem is clearly not layout-related

## Step 4: Report Fixes

Write `PROJECT_DIR/auditor.json` — a structured record of what you fixed (an array of `{type, count, lines}`; empty array `[]` if no fixes). Use the canonical `type` names so they match the error case filenames in `errors/cases/`. The format and the full type list are in **[`references/report_types.json`](references/report_types.json)**.

## Output

Modified `PROJECT_DIR/index.html` with layout issues fixed, plus `PROJECT_DIR/auditor.json` with the structured fix report.

Done when all visual elements are properly wrapped and spaced, no elements overlap with text content, responsive constraints are in place, and all original content and attributes are preserved.