/kb-report-generation

name: kb-report-generation
description: Reference data, not a reviewer. Format accessibility audit reports with severity scoring (0-100, A-F grades), scorecard computation, and compliance exports including VPAT/ACR and remediation priorities.
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: reference
  domain: cross-cutting
  output: none
  effort: low
  title: Report Generation

Report Generation

Report File

Default output: `DOCUMENT-ACCESSIBILITY-AUDIT.md` in the project root.

Required Sections

Every audit report MUST include these sections:

1. **Audit Information** - date, auditor, profile, scope, counts 2. **Executive Summary** - totals, pass rate, most common issue, effort estimate 3. **Cross-Document Patterns** - recurring issues, systemic failures 4. **Findings by File** - per-document issues with rule ID, severity, location, WCAG, impact, remediation 5. **Findings by Rule (Cross-Reference)** - rule-level aggregation across files 6. **What Passed** - acknowledge clean documents and categories 7. **Remediation Priority** - ordered by impact (Immediate / Soon / When Possible) 8. **Accessibility Scorecard** - per-document scores and grades 9. **Metadata Dashboard** - document properties health 10. **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

The score and grade in a rendered report come from `skills/a11y-core/scripts/merge-findings.mjs` (weights critical 10, serious 5, moderate 2, minor 1; confidence high 1.0, medium 0.7, low 0.4; grades A 90+, B 80+, C 70+, D 60+, F below). The formula is in `kb-web-severity-scoring`. Map a document checker's levels onto the canonical severities first (`kb-severity-mapping`) rather than scoring errors and warnings directly.

Score Grades

Each score band, with its grade and meaning.

| Score | Grade | Meaning | |-------|-------|---------| | 90-100 | A | Excellent - few barriers found | | 80-89 | B | Good - some barriers found | | 70-79 | C | Needs Work - many barriers remain | | 60-69 | D | Poor - significant barriers | | 0-59 | F | Failing - unusable with AT |

Organization Modes

Each mode, with description and best for.

| 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

Each level, with its criteria.

| 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

The current ITI template is VPAT 2.5Rev (24 April 2025), as of October 2026.

• **VPAT 2.5 (WCAG)** - maps to WCAG 2.0, 2.1 and 2.2 criteria
• **VPAT 2.5 (508)** - maps to Revised Section 508 standards (WCAG 2.0 AA)
• **VPAT 2.5 (EU)** - maps to EN 301 549; the template still points at V3.2.1 (WCAG 2.1 AA)
• **VPAT 2.5 (INT)** - International edition (all three combined)

4.1.1 Parsing is obsolete in WCAG 2.2 and is never reported as a 2.2 failure. For the 4.1.1 rows that 2.0 and 2.1 based tables still carry, follow `skills/kb-legal-compliance-mapping/SKILL.md`. Date every ACR and say which edition and standard versions it covers.

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