git:20260922.cd88753 to git:20261028.d473f9f

22 added, 23 removed. Audit A to A.

---

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

- ```text

- 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)

- ```

+ 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, with its grade and meaning.

+ Each score band, with its grade and meaning.

| 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 |

+ | 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

- - **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

+ 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