---
name: report-generation
description: Audit report formatting, severity scoring, scorecard computation, and compliance export for document accessibility audits. Use when generating DOCUMENT-ACCESSIBILITY-AUDIT.md reports, computing document severity scores (0-100 with A-F grades), creating VPAT/ACR compliance exports, or formatting remediation priorities.
Report Generation
Report File
Default output: DOCUMENT-ACCESSIBILITY-AUDIT.md in the project root.
Required Sections
Every audit report MUST include these sections:
- Audit Information - date, auditor, profile, scope, counts
- Executive Summary - totals, pass rate, most common issue, effort estimate
- Cross-Document Patterns - recurring issues, systemic failures
- Findings by File - per-document issues with rule ID, severity, location, WCAG, impact, remediation
- Findings by Rule (Cross-Reference) - rule-level aggregation across files
- What Passed - acknowledge clean documents and categories
- Remediation Priority - ordered by impact (Immediate / Soon / When Possible)
- Accessibility Scorecard - per-document scores and grades
- Metadata Dashboard - document properties health
- Confidence Summary - breakdown by confidence level
Optional Sections (include when applicable)
- Template Analysis - when batch scanning detects shared templates
- Comparison Report - when re-scanning against a baseline
- CI/CD Recommendations - when no config files exist
Severity Scoring Formula
Document Score = 100 - (sum of weighted findings)
Weights:
Error (high confidence): -10 points
Error (medium confidence): -7 points
Error (low confidence): -3 points
Warning (high confidence): -3 points
Warning (medium confidence):-2 points
Warning (low confidence): -1 point
Tips: 0 points
Floor: 0 (minimum score)
Score Grades
| Score |
Grade |
Meaning |
| 90-100 |
A |
Excellent - minor or no issues |
| 75-89 |
B |
Good - some warnings, few errors |
| 50-74 |
C |
Needs Work - multiple errors |
| 25-49 |
D |
Poor - significant accessibility barriers |
| 0-24 |
F |
Failing - critical barriers, likely unusable with AT |
Organization Modes
| Mode |
Description |
Best For |
| By file |
Group all issues under each document |
Small batches (< 10 files) |
| By issue type |
Group all instances of each rule across documents |
Seeing patterns |
| By severity |
Critical first, then serious, moderate, minor |
Prioritizing fixes |
VPAT/ACR Compliance Export
Conformance Levels
| Level |
Criteria |
| Supports |
No findings for this WCAG criterion across any document |
| Partially Supports |
Some documents pass, some fail |
| Does Not Support |
All or most documents fail |
| Not Applicable |
Criterion does not apply to scanned document types |
Supported VPAT Editions
- VPAT 2.5 (WCAG) - maps to WCAG 2.2 criteria
- VPAT 2.5 (508) - maps to Revised Section 508 standards
- VPAT 2.5 (EN 301 549) - maps to EU accessibility directive
- VPAT 2.5 (INT) - International edition (all three combined)
Remediation Tracking
When comparing against a baseline audit report:
| Status |
Meaning |
| Fixed |
Issue was in previous report but is now resolved |
| New |
Issue was not in previous report but appears now |
| Persistent |
Issue remains from previous report |
| Regressed |
Issue was previously fixed but has returned |
Progress Metrics
- Issue reduction percentage:
(fixed / previous_total) * 100
- Score change:
current_score - previous_score
- Documents improved: count of documents with higher scores
1---2name: report-generation3description: ---4---5---6name: report-generation7description: Audit report formatting, severity scoring, scorecard computation, and compliance export for document accessibility audits. Use when generating DOCUMENT-ACCESSIBILITY-AUDIT.md reports, computing document severity scores (0-100 with A-F grades), creating VPAT/ACR compliance exports, or formatting remediation priorities.8---9<!-- CANONICAL SOURCE: .github/skills/report-generation/SKILL.md -- Edit the canonical source; sync to Gemini via scripts/check-gemini-sync.ps1 -->1011# Report Generation1213## Report File1415Default output: `DOCUMENT-ACCESSIBILITY-AUDIT.md` in the project root.1617## Required Sections1819Every audit report MUST include these sections:20211. **Audit Information** - date, auditor, profile, scope, counts222. **Executive Summary** - totals, pass rate, most common issue, effort estimate233. **Cross-Document Patterns** - recurring issues, systemic failures244. **Findings by File** - per-document issues with rule ID, severity, location, WCAG, impact, remediation255. **Findings by Rule (Cross-Reference)** - rule-level aggregation across files266. **What Passed** - acknowledge clean documents and categories277. **Remediation Priority** - ordered by impact (Immediate / Soon / When Possible)288. **Accessibility Scorecard** - per-document scores and grades299. **Metadata Dashboard** - document properties health3010. **Confidence Summary** - breakdown by confidence level3132### Optional Sections (include when applicable)3334- **Template Analysis** - when batch scanning detects shared templates35- **Comparison Report** - when re-scanning against a baseline36- **CI/CD Recommendations** - when no config files exist3738## Severity Scoring Formula3940```text41Document Score = 100 - (sum of weighted findings)4243Weights:44 Error (high confidence): -10 points45 Error (medium confidence): -7 points46 Error (low confidence): -3 points47 Warning (high confidence): -3 points48 Warning (medium confidence):-2 points49 Warning (low confidence): -1 point50 Tips: 0 points5152Floor: 0 (minimum score)53```5455## Score Grades5657| Score | Grade | Meaning |58|-------|-------|---------|59| 90-100 | A | Excellent - minor or no issues |60| 75-89 | B | Good - some warnings, few errors |61| 50-74 | C | Needs Work - multiple errors |62| 25-49 | D | Poor - significant accessibility barriers |63| 0-24 | F | Failing - critical barriers, likely unusable with AT |6465## Organization Modes6667| Mode | Description | Best For |68|------|-------------|----------|69| By file | Group all issues under each document | Small batches (< 10 files) |70| By issue type | Group all instances of each rule across documents | Seeing patterns |71| By severity | Critical first, then serious, moderate, minor | Prioritizing fixes |7273## VPAT/ACR Compliance Export7475### Conformance Levels7677| Level | Criteria |78|-------|----------|79| Supports | No findings for this WCAG criterion across any document |80| Partially Supports | Some documents pass, some fail |81| Does Not Support | All or most documents fail |82| Not Applicable | Criterion does not apply to scanned document types |8384### Supported VPAT Editions8586- **VPAT 2.5 (WCAG)** - maps to WCAG 2.2 criteria87- **VPAT 2.5 (508)** - maps to Revised Section 508 standards88- **VPAT 2.5 (EN 301 549)** - maps to EU accessibility directive89- **VPAT 2.5 (INT)** - International edition (all three combined)9091## Remediation Tracking9293When comparing against a baseline audit report:9495| Status | Meaning |96|--------|---------|97| Fixed | Issue was in previous report but is now resolved |98| New | Issue was not in previous report but appears now |99| Persistent | Issue remains from previous report |100| Regressed | Issue was previously fixed but has returned |101102### Progress Metrics103104- Issue reduction percentage: `(fixed / previous_total) * 100`105- Score change: `current_score - previous_score`106- Documents improved: count of documents with higher scores
Community-Access