quality-report-generate

Quality Report Generate Skill

Purpose

This skill generates the final quality report documenting everything about a chapter's generation and validation. The report:

• Aggregates all validation results from previous gates
• Calculates quality metrics (content size, structure complexity, accuracy)
• Generates human-readable markdown report for review
• Creates machine-readable JSON metrics for tracking and CI/CD
• Provides deployment decision (pass/fail/requires-review)

This is the final skill before validation gates, producing the evidence needed to approve or reject a chapter for deployment.

What to Do

1. Collect all validation artifacts
2. Load validation_structure.json (Gate 1 results)
3. Load validation_semantic.json (Gate 2 results)
4. Load consolidation_log.json (consolidation data)
5. Load final chapter_XX.html file

1. Extract metadata from chapter
2. Parse HTML to extract structure
3. Count content elements (headings, paragraphs, lists)
4. Calculate word count and content size
5. Verify CSS class usage

1. Calculate quality metrics
2. Overall validation score (0-100)
3. Structural compliance percentage
4. Semantic compliance percentage
5. Content completeness estimate
6. Accuracy score (if reference data available)

1. Generate markdown report
2. Create human-readable verification report
3. Include summary status (✅ PASS / ⚠️ REVIEW / ❌ FAIL)
4. Document all validation results
5. List findings and recommendations

1. Generate JSON metrics
2. Machine-readable metrics for tracking
3. Suitable for CI/CD pipelines
4. Enable automated quality dashboards
5. Support trend analysis

1. Save both report formats
2. Save: output/chapter_XX/chapter_artifacts/CHAPTER_XX_VERIFICATION.md
3. Save: output/chapter_XX/chapter_artifacts/quality_metrics.json
4. Timestamp both files
5. Create summary statistics

Input Files

Validation reports (from previous gates):

• validation_structure.json - HTML structure validation results
• validation_semantic.json - Semantic validation results
• consolidation_log.json - Page consolidation metadata

Chapter content:

• chapter_XX.html - Final consolidated HTML
• page_artifacts/page_YY/*.html - Individual page HTML (optional, for analysis)

Reference data (optional):

• page_artifacts/page_YY/02_page_XX.png - Original PDF pages (for visual comparison)

Quality Metrics Calculation

Overall Validation Score (0-100)

base_score = 100

# Deduct for structure issues
if structure_errors > 0:
    base_score -= (structure_errors * 10)

# Deduct for semantic issues
if semantic_errors > 0:
    base_score -= (semantic_errors * 5)

# Deduct for warnings
warning_count = structure_warnings + semantic_warnings
base_score -= (warning_count * 2)

# Bonus for semantic classes
if semantic_classes_ratio > 0.8:
    base_score += 5

overall_score = max(0, min(100, base_score))

Content Completeness

expected_pages = last_page - first_page + 1
pages_with_content = count_pages_with_substantial_content()
completeness_percent = (pages_with_content / expected_pages) * 100

Structural Compliance

checks_passed = structure_validation_checks_passed
checks_total = structure_validation_checks_total
compliance_percent = (checks_passed / checks_total) * 100

Semantic Compliance

required_classes = [
    'page-container', 'page-content', 'chapter-header',
    'section-heading', 'paragraph', 'bullet-list'
]
found_classes = [c for c in required_classes if c in html]
compliance_percent = (len(found_classes) / len(required_classes)) * 100

Output: Markdown Report

Path: output/chapter_XX/chapter_artifacts/CHAPTER_XX_VERIFICATION.md

Example structure:

# Chapter 2 HTML Accuracy Verification Report

## Summary
**Status**: ✅ **VERIFIED ACCURATE**

The Chapter 2 HTML document has been thoroughly verified for accuracy and quality. All validation gates passed successfully.

---

## Overall Quality Metrics

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| **Overall Quality Score** | 96/100 | ≥85 | ✅ PASS |
| **Structure Validation** | 100% | 100% | ✅ PASS |
| **Semantic Validation** | 98% | ≥90% | ✅ PASS |
| **Content Completeness** | 100% | 100% | ✅ PASS |
| **Visual Accuracy** | 94% | ≥85% | ✅ PASS |

---

## Content Summary

### Pages
- **Book Pages**: 16-29 (14 pages)
- **PDF Indices**: 15-28
- **Chapter**: 2 - Rights in Real Estate

### Content Elements
- **Total Paragraphs**: 156
- **Total Headings**: 28 (1 h1, 4 h2, 23 h4)
- **Total Lists**: 12 (132 total items)
- **Total Tables/Exhibits**: 3
- **Total Images**: 5
- **Total Words**: 12,547

---

## Validation Results

### ✅ HTML Structure Validation (PASSED)

All structural checks passed:
- ✓ HTML5 DOCTYPE valid
- ✓ `<html>`, `<head>`, `<body>` tags properly formed
- ✓ Meta charset and viewport tags present
- ✓ Title tag with descriptive content
- ✓ CSS stylesheet linked correctly
- ✓ `<div class="page-container">` wrapper present
- ✓ `<main class="page-content">` structure valid
- ✓ All tags properly matched and closed
- ✓ No unclosed or improperly nested tags

**Errors**: 0
**Warnings**: 0

### ✅ Semantic Validation (PASSED)

All semantic checks passed:
- ✓ Required CSS classes present and correct
- ✓ Heading hierarchy valid (no jumps, logical flow)
- ✓ All paragraphs properly formatted
- ✓ All lists correctly structured
- ✓ Tables properly formatted
- ✓ Semantic class usage consistent throughout
- ✓ Page maintains continuous format (no pagination)

**Errors**: 0
**Warnings**: 0

### ✅ Visual Accuracy Check (PASSED)

Comparison with original PDF pages:
- Overall similarity: 94%
- Page-by-page average: 94%
- All pages ≥ 85% threshold
- Layout matches original
- Content positioning accurate
- Text rendering correct

---

## Consolidation Details

**Chapter Opening**: Page 16 (Chapter header and navigation included)
**Consolidation**: Pages 16-29 merged into single continuous document
**Pages Merged**: 14
**Page Headers Removed**: 13 (continuation pages)
**Duplicate Content**: None detected

**Consolidation Log**:

{ "pages_merged": 14, "pages_include": [...], "heading_hierarchy": { "h1": 1, "h2": 4, "h4": 23 }, "content_statistics": { "paragraphs": 156, "lists": 12, "tables": 3, "images": 5, "total_words": 12547 } }

---

## CSS Classes Used

**Core Structure**: page-container, page-content, chapter-header (6 classes)
**Content**: section-heading, subsection-heading, paragraph, bullet-list, bullet-item (12 classes)
**Exhibits**: exhibit, exhibit-table, exhibit-title, exhibit-header (4 classes)
**Navigation**: section-navigation, nav-item (2 classes)
**Special**: section-divider, page-footer (2 classes)

**Total unique classes**: 26
**Classes found as required**: 6/6 (100%)

---

## Issues & Findings

### ✅ No Critical Issues Found
- ✓ No missing sections
- ✓ No missing content
- ✓ No structural problems
- ✓ No broken internal links
- ✓ No invalid HTML
- ✓ No semantic violations

### ⚠️ Minor Notes
- None - all validation gates passed

---

## Generation Process

**Extraction**: Rich data extracted from PDF pages (text, fonts, images)
**ASCII Preview**: Structural layout created for AI reference
**AI Generation**: Individual pages generated using 3-input approach:
- Visual reference (PNG rendering of PDF)
- Parsed text data (JSON with metadata)
- Layout structure (ASCII preview)
**Structure Validation**: HTML5 compliance verified
**Consolidation**: Pages merged into continuous chapter
**Semantic Validation**: Structure and classes verified
**Quality Report**: Final metrics and status

---

## Accuracy Assessment

| Criterion | Result | Assessment |
|-----------|--------|------------|
| **Content Completeness** | 100% | All sections present |
| **Page Coverage** | 14/14 | All pages included |
| **Heading Acc