ai-visual-accuracy-check

What this skill does

# AI Visual Accuracy Check Skill

## Purpose

This is a **BLOCKING quality gate** that uses **AI to validate visual accuracy** of generated HTML against the original PDF page. Unlike pixel-perfect comparison, AI understands:

- Visual hierarchy and layout intent
- Contextual differences (web rendering vs PDF)
- Whether readers would have similar experience
- Trade-offs between CSS limitations and HTML accuracy

The AI provides:
- Objective similarity score (0-100%)
- Breakdown by evaluation criteria
- Specific differences noted
- Clear pass/fail recommendation
- Explanation for decisions

This combines **AI's contextual understanding** with **deterministic gating** (must pass 85+ to continue).

## What to Do

1. **Load input files**
   - Read `chapter_XX.html` (generated consolidated HTML)
   - Read `02_page_XX.png` (original PDF page image)

2. **Render HTML to image**
   - Use headless browser (Playwright/Selenium) to render HTML as PNG
   - Capture full page screenshot
   - Save rendered image for comparison

3. **Invoke Claude with visual comparison**
   - Attach original PDF PNG as image 1
   - Attach rendered HTML screenshot as image 2
   - Request detailed visual comparison
   - Ask AI to score on multiple criteria

4. **Parse AI response**
   - Extract overall similarity score
   - Extract criterion-specific scores
   - Parse differences noted
   - Get recommendation (PASS/FAIL)

5. **Save comparison report**
   - Save to: `output/chapter_XX/chapter_artifacts/ai_visual_accuracy.json`
   - Include timestamp, inputs used, AI model

6. **Make gate decision**
   - If score ≥ 85: PASS (exit code 0, continue)
   - If score < 85: FAIL (exit code 1, trigger hook)

## Input Parameters

```
html_file: <str>          - Path to chapter_XX.html
pdf_page_png: <str>       - Path to original PDF page PNG (or multiple for multi-page)
output_dir: <str>         - Directory for report
chapter: <int>            - Chapter number (for reporting)
book_pages: <str>         - Page range (for reporting)
threshold: <float>        - Minimum score to pass (default: 85.0)
```

## AI Prompt Template

```
You are validating the visual accuracy of a generated HTML page against the original PDF.

ORIGINAL PDF PAGE:
[PNG Image of original PDF page attached]

GENERATED HTML (Rendered):
[PNG Image of rendered HTML page attached]

TASK:
Compare these two images and determine if the HTML accurately recreates the visual appearance and layout of the PDF page.

EVALUATION CRITERIA:

1. Layout Match (40% weight)
   - Overall page structure matches original
   - Sections in correct order and position
   - Spacing between elements appropriate
   - Page dimensions/aspect ratio similar

2. Visual Hierarchy (30% weight)
   - Headings stand out with appropriate prominence
   - Section breaks clearly visible
   - Emphasis (bold, italic) preserved or equivalent
   - Visual relationships between elements clear

3. Content Positioning (20% weight)
   - Elements aligned correctly (left, center, right)
   - Lists indented with proper spacing
   - Tables/exhibits positioned and aligned correctly
   - Paragraph flow matches original

4. Typography & Styling (10% weight)
   - Font sizes relative to each other correct
   - Text styling appropriate (bold, italic, caps)
   - Color scheme preserved (if applicable)
   - Overall readability equivalent or better

SCORING GUIDELINES:

For each criterion:
- 90-100%: Excellent, no issues
- 80-89%: Good, minor cosmetic differences
- 70-79%: Acceptable, noticeable but not critical
- Below 70%: Poor, significant differences

IMPORTANT CONTEXT:
- HTML rendering in browser may differ slightly from PDF (spacing, fonts)
- Focus on INTENT and READABILITY, not pixel-perfect match
- Small spacing/margin differences (2-5px) are acceptable
- Font rendering differences are acceptable if hierarchy preserved
- Web rendering constraints are acceptable (no absolute PDF positioning)

OUTPUT FORMAT:

Provide your analysis in this exact JSON format:

```json
{
  "overall_score": 92.5,
  "threshold": 85.0,
  "recommendation": "PASS",
  "criteria_analysis": {
    "layout_match": {
      "score": 94,
      "feedback": "Overall page structure matches well. Section order correct, spacing appropriate."
    },
    "visual_hierarchy": {
      "score": 90,
      "feedback": "Headings clearly distinguished. Visual relationships preserved. Minor font size variance acceptable."
    },
    "content_positioning": {
      "score": 91,
      "feedback": "Element alignment correct. Lists properly indented. Tables positioned correctly."
    },
    "typography_styling": {
      "score": 88,
      "feedback": "Text styling preserved. Bold and italic distinctions clear. Readability excellent."
    }
  },
  "differences_noted": [
    "Paragraph line-height 1.6 vs 1.5 in PDF (acceptable, improves readability)",
    "Bullet list indentation 20px vs 15px in PDF (acceptable, clear and readable)"
  ],
  "visual_fidelity_assessment": "EXCELLENT",
  "confidence_level": 0.95,
  "explanation": "The HTML accurately recreates the PDF page layout and visual hierarchy. All major elements are positioned correctly. Minor spacing and font differences are within acceptable tolerances for web rendering and actually improve readability.",
  "pass_fail_verdict": "PASS"
}
```

VALIDATION:
- Overall score must be numeric (0-100)
- All criteria must have scores
- Recommendation must be PASS or FAIL
- Explanation must be clear and actionable
```

## Process Flow

```
┌─ Load HTML & PNG ──────────────────┐
│ • chapter_XX.html                  │
│ • 02_page_XX.png                   │
└────────┬────────────────────────────┘
         │
         ▼
┌─ Render HTML to PNG ───────────────┐
│ • Headless browser                 │
│ • Full page screenshot             │
│ • Save to temp location            │
└────────┬────────────────────────────┘
         │
         ▼
┌─ Invoke Claude API ────────────────┐
│ • Send original PDF PNG            │
│ • Send rendered HTML PNG           │
│ • Multi-modal comparison prompt    │
│ • Request JSON response            │
└────────┬────────────────────────────┘
         │
         ▼
┌─ Parse & Save Report ──────────────┐
│ • Extract JSON from response       │
│ • Validate score 0-100             │
│ • Save to JSON file                │
└────────┬────────────────────────────┘
         │
         ▼
┌─ Gate Decision ────────────────────┐
│ • If score ≥ 85: PASS              │
│ • If score < 85: FAIL              │
└────────┬────────────────────────────┘
         │
         ▼
  Exit with code 0 or 1
```

## Output File Format

**Path**: `output/chapter_XX/chapter_artifacts/ai_visual_accuracy.json`

```json
{
  "chapter": 2,
  "book_pages": "16-29",
  "validation_type": "ai_visual_accuracy",
  "validation_timestamp": "2025-11-08T14:45:00Z",
  "overall_score": 92.5,
  "threshold": 85.0,
  "status": "PASS",
  "ai_model": "claude-3-5-sonnet-20241022",
  "inputs": {
    "html_file": "chapter_02.html",
    "original_pdf_png": "02_page_16.png",
    "rendered_html_png": "rendered_chapter_02.png"
  },
  "criteria_scores": {
    "layout_match": 94,
    "visual_hierarchy": 90,
    "content_positioning": 91,
    "typography_styling": 88
  },
  "differences": [
    "Paragraph line-height 1.6 vs 1.5 in PDF (acceptable)",
    "Bullet list indentation 20px vs 15px in PDF (acceptable)"
  ],
  "visual_fidelity": "EXCELLENT",
  "confidence": 0.95,
  "explanation": "The HTML accurately recreates the PDF page layout and visual hierarchy...",
  "recommendation": "PASS",
  "notes": "All criteria well within acceptable ranges. Minor web rendering differences do not impact readability or intent."
}
```

## Multi-Page Chapters

For chapters spanning multiple pages:

1. **Option A: Compare key pages**
   - Compare opening page (establishes style)
   - Compare middle pages (continuation pages)
   - Compare final pages (consistency check)
   - Average scores across pages

2. **Option B: Compare consolidated view**
   - Render fu