Quality Check

---
name: post-implementation-audit
description: Read-only audit of completed code changes. Use after implementation or remediation to verify requirements, correctness, regressions, relevant verification, and commit scope. Do not use to implement or fix changes.
---

# Post-Implementation Audit

Independently audit completed code changes using available evidence.

This workflow is read-only. Find meaningful problems when they exist; do not manufacture findings.

## Scope and boundary

Follow the current task, applicable repository instructions such as `AGENTS.md`, and the actual implementation context.

Do not broaden the audit merely because additional review is possible.

Do not implement, remediate, refactor, stage, commit, or intentionally modify repository state while this workflow is active.

If a required verification step would intentionally modify tracked files, do not run it during the audit. Report it as a verification limitation and return that work to an implementation/remediation phase.

Unexpected side effects from otherwise appropriate verification commands must be reported, not reverted or cleaned up.

Do not create an audit file unless explicitly requested.

## 1. Establish target and baseline

Determine what change is actually being audited before judging it.

When Git is available, prefer the baseline in this order:

1. explicit baseline or commit range from the task;
2. a known implementation start point supported by context;
3. clearly attributable staged or working-tree changes.

Never select an arbitrary number of recent commits as the baseline.

Distinguish implementation changes from pre-existing or unrelated repository changes.

If the boundary cannot be established reliably, state the limitation and audit only what can be attributed with reasonable confidence.

Do not invent missing requirements, acceptance criteria, history, or implementation boundaries.

## 2. Verify requirements, correctness, and regressions

Trace available requirements and acceptance criteria to the implementation.

Check for meaningful issues such as:

- missing or partial behavior;
- incorrect requirement interpretation;
- regressions or unintended behavior changes;
- scope creep or unrelated modifications;
- incorrect logic or state transitions;
- relevant error or failure paths;
- plausible boundary, lifecycle, async, concurrency, persistence, caching, or integration problems.

Inspect enough surrounding code to understand the changed behavior.

Only investigate risk areas that are plausible for the implementation.

Review security, performance, data integrity, or deployment concerns only when the change makes them relevant.

Do not report subjective style preferences or speculative possibilities as defects.

A maintainability concern is a finding only when it creates a concrete correctness, reviewability, change-safety, or long-term engineering risk.

## 3. Verify evidence

Run the smallest relevant set of non-mutating verification commands needed for confidence.

Expand verification when scope or risk warrants it.

Never claim that a command, test, path, or behavior was verified unless it actually was.

If important verification cannot be completed, record:

- what was not verified;
- why;
- what confidence is lost.

A verification limitation is not automatically a finding.

Treat it as a finding only when the missing verification itself violates an explicit requirement or represents a concrete defect.

## 4. Review commits when applicable

When commits are part of the audited implementation, verify that each represents one coherent concern and is independently understandable, reviewable, and reasonably revertible.

Report material problems such as:

- unrelated concerns mixed together;
- hidden scope expansion;
- accidental unrelated changes;
- misleading commit boundaries;
- excessive size that materially harms reviewability or rollback safety.

Do not require commits when none were authorized or expected.

## 5. Complete the full audit

Do not stop at the first issue.

Complete the full in-scope review and collect every meaningful finding supported by evidence.

Each finding must be backed by code, diff, test output, command output, reproducible behavior, or a credible demonstrated failure path.

Distinguish fact from inference.

After completing the audit, report the result and stop. Do not remediate findings.

## Severity

Use severity only for actual findings:

**Critical** — catastrophic failure, severe security compromise, irreversible data loss/corruption, or fundamentally unusable core behavior.

**High** — major incorrect behavior, serious regression, significant security/reliability failure, or failure of an important requirement.

**Medium** — real actionable defect with bounded impact.

**Low** — minor but legitimate defect with limited concrete impact.

Do not use `Low` for optional polish or subjective preference.

## Result

Use exactly one primary result:

### CLEAR

Use when:

- no meaningful finding remains;
- intended behavior is sufficiently established;
- relevant verification completed successfully;
- no material unexplained verification gap remains;
- no material scope contamination exists.

### FINDINGS

Use when one or more meaningful implementation findings exist.

Verification limitations may be reported alongside `FINDINGS`.

### INCOMPLETE

Use when no meaningful implementation defect has been established, but missing context or important verification prevents a reliable `CLEAR`.

Do not treat absence of discovered defects as proof of correctness.

## Re-audit

When previous findings are available, preserve their identifiers and mark each:

- `RESOLVED`
- `UNRESOLVED`
- `NOT VERIFIED`

Verify the underlying issue, not only its visible symptom, and check whether remediation introduced regressions.

Then perform a fresh audit of the affected scope.

Do not invent prior finding IDs when they are unavailable.

## Output

Start with:

**Result:** `CLEAR` / `FINDINGS` / `INCOMPLETE`

Briefly state:

- scope audited;
- baseline used;
- important evidence inspected;
- verification commands actually executed;
- material limitations.

For each new finding include:

**ID:** `AUDIT-001`  
**Severity:** Critical / High / Medium / Low  
**Evidence:** concrete supporting evidence  
**Impact:** concrete failure or risk  
**Recommended remediation:** smallest appropriate correction  
**Verification:** how a re-audit can prove resolution

For re-audited findings also include:

**Status:** RESOLVED / UNRESOLVED / NOT VERIFIED

For `INCOMPLETE`, state what evidence is missing.

For `CLEAR`, state that no meaningful findings remain and summarize the evidence supporting that conclusion.

Do not invent owners, deadlines, metrics, findings, or recommendations merely to make the report appear more comprehensive.

---
name: markdown-accessibility-checker
description: Reviews Markdown documentation (READMEs, docs sites, wikis, blog posts, changelogs) for accessibility - missing or poor image alt text, heading structure, vague or duplicate link text, bare URLs, empty table headers, color-only instructions, ALL CAPS, and emoji bullets - then writes good alt text for each image from context and returns a fix list or a corrected file. Use when a user asks to "check my README for accessibility", "write alt text for these images", "make our docs screen reader friendly", or wants an accessibility check for Markdown in CI.
---

# Markdown Accessibility Checker

You make Markdown documents work for everyone, including people who use screen readers, keyboard navigation, magnification, or reading aids. You find the problems a script can detect, then do the part a script cannot: write meaningful alt text and link text that fit the document's purpose.

## Files in this skill

- `scripts/check_md_a11y.py` - scans Markdown files or folders and reports problems with line numbers and severities (Python 3 standard library only)
- `references/alt-text-guide.md` - how to write alt text by image type (screenshots, diagrams, charts, photos, logos, badges, decorative images)
- `references/structure-and-links.md` - headings, link text, tables, lists, emphasis, and what each rule in the script means
- `templates/a11y-review.md` - the review report and the alt text worksheet
- `examples/example-readme-review.md` - a worked review of a project README

## Workflow

### 1. Scope the review
Ask which files or folders to check, who reads them (developers, end users, students), and whether the user wants a report, a corrected file, or both. If the documents are rendered by a site generator, ask whether it adds its own page title (then the Markdown may not need an H1).

### 2. Run the checker
```bash
python3 scripts/check_md_a11y.py README.md docs/
python3 scripts/check_md_a11y.py docs/ --json
python3 scripts/check_md_a11y.py docs/ --fail-on warn     # for CI
```
It ignores fenced code blocks and inline code. HIGH means content is lost for some readers (missing alt, empty link, empty heading), WARN should be fixed, INFO needs a human look. If you cannot run the script, check the same rules by reading the file and say so.

### 3. Write alt text
For every image flagged, and for every image with existing alt text, decide its purpose using `references/alt-text-guide.md`:
- Read the text around it: what is the image for at this point in the document?
- If you can see the image, describe what matters for that purpose. If you cannot, ask the user, or write a clearly marked draft from the file name and context (for example "DRAFT: check against the image").
- Decorative images get empty alt text; in Markdown prefer removing them, or use HTML `<img alt="">`.
Fill in the alt text worksheet in `templates/a11y-review.md`.

### 4. Fix structure and links
Apply `references/structure-and-links.md`: one H1, no skipped levels, real headings instead of bold lines, descriptive unique link text, tables with headers, instructions that do not rely on color alone.

### 5. Deliver
- Report: fill in `templates/a11y-review.md`, as in `examples/example-readme-review.md`, with the most important fixes first.
- Corrected file: return the full Markdown with fixes applied and a short change list. Do not change meaning, code samples, or links' destinations.
- Rerun the checker on the corrected file and include the before and after counts.

## Rules
- Never invent what an image shows. If you have not seen it, mark the alt text as a draft.
- Keep alt text short (usually under 150 characters); put long explanations (charts, diagrams) in the text or a caption and say so in the alt.
- Do not start alt text with "image of" or "picture of".
- Remember that automated checks find only part of the problems; always mention what still needs a manual check (color contrast in images, reading order, video captions).
- Respect the author's voice; fix accessibility, not style.
FILE:references/alt-text-guide.md
# Alt text guide

Alt text replaces the image for people who cannot see it. Ask: "If I read this document aloud, what would I say at this point instead of showing the image?" The answer depends on why the image is there, not only on what is in it.

## Basics
- Be specific and short: usually 5 to 20 words, rarely more than 150 characters.
- Lead with the important part. Do not start with "image of", "picture of", or "screenshot of" unless the type itself matters ("Screenshot" can help when the reader needs to find the same screen).
- End with a period so screen readers pause.
- Do not repeat the caption or the sentence next to the image word for word.
- Include text that appears in the image if the reader needs it (button labels, error messages).

## By image type

### Screenshots of an app or website
State the screen and the one thing the reader should notice.
- Weak: "screenshot"
- Better: "Settings screen with the Units toggle set to Metric."

### Hero images and banners
If it only sets the mood, it is decorative. If it shows the product, describe it in one sentence.
- "Trailhead Weather on a phone, showing a three-day forecast for a mountain pass."

### Diagrams and flowcharts
Give the main idea in the alt, and the full structure in the text or a list right after the image.
- Alt: "Architecture diagram: the mobile app calls the API, which reads from a forecast cache and a weather provider. Details in the list below."

### Charts and graphs
Give the type, the subject, and the key takeaway; put the data in a table if readers need numbers.
- "Line chart of daily active users, January to June 2026, rising from 2,000 to 9,500 with a dip in April."

### Photos
Describe what matters for the document's purpose: subject, action, setting.
- "Snow-covered ridge trail with orange marker poles leading to a hut."

### Logos
Use the organization or product name, plus "logo" only if it helps: "Trailhead Weather logo."
When the logo is a link, describe the destination: "Trailhead Weather home."

### Badges (build status, version, license)
Write the information the badge shows: "Build: passing", "License: MIT", "Version 2.4.1".

### Icons inside text or links
If the icon has a function, describe the function ("Download"); if it repeats nearby text, it is decorative.

### Animated GIFs and short videos
Describe what happens: "Animation: dragging a pin onto the map adds a new trailhead to the list." Videos also need captions and, for important content, a text alternative.

### Decorative images
Dividers, background textures, and purely visual flourishes. In HTML use `alt=""` so screen readers skip them. In Markdown, `![](divider.png)` is ambiguous (often a mistake), so prefer removing the image or using `<img src="divider.png" alt="">`.

## Common mistakes
- File names as alt text: "IMG_2041.jpg", "hero-final-v3".
- One word: "image", "logo", "chart".
- Keyword stuffing for search engines.
- Different alt text for the same image used in several places.
- Describing colors or layout when the reader needs the information, not the look.
FILE:references/structure-and-links.md
# Structure, links, and what each rule means

Screen reader users often jump through a document by headings or by links. Good structure is what makes that possible.

## Headings
| Rule | Severity | Why | Fix |
|---|---|---|---|
| empty-heading | HIGH | An empty heading is announced as "heading level 2" with nothing after it. | Add text or remove the #. |
| no-h1 | WARN | The page has no title in the heading outline. | Start with one `# Title`. Skip this if the site generator adds the H1 from front matter. |
| multiple-h1 | WARN | Several titles confuse the outline. | Keep one H1; use `##` for sections. |
| heading-skip | WARN | Jumping from H2 to H4 suggests a missing section. | Use the next level down (H3). Pick levels for structure, not for font size. |
| fake-heading | INFO | A bold line looks like a heading but is not in the outline. | Use a real heading if it starts a section; keep bold if it is just emphasis. |
| no-headings | INFO | Long text without headings is hard to scan. | Add section headings every few paragraphs. |

## Links
| Rule | Severity | Why | Fix |
|---|---|---|---|
| empty-link | HIGH | The link has no accessible name. | Add descriptive text. |
| vague-link | WARN | "Click here" or "read more" means nothing in a list of links. | Name the destination: "download the latest release", "setup guide". |
| same-text-different-url | WARN | Two links called "docs" that go to different places are indistinguishable. | Make each text unique: "API reference", "setup guide". |
| url-as-link-text | INFO | Long URLs are read character by character. | Use a short description; keep the URL only if readers must copy it. |
| bare-url | INFO | Same as above, and not always clickable. | Wrap in a descriptive link. |

Link text tips: put the important words first, keep it short, say when a link opens a file ("pricing sheet (PDF, 2 MB)"), and do not use "link" in the text.

## Images
| Rule | Severity | Why |
|---|---|---|
| img-missing-alt | HIGH | `![](file.png)` gives no alternative; some readers announce the file name. |
| img-no-alt | HIGH | `<img>` without an alt attribute; screen readers fall back to the file name. |
| img-generic-alt | WARN | "image", "screenshot", "logo" alone carry no information. |
| img-filename-alt | WARN | "IMG_2041.jpg" is not a description. |
| img-long-alt | WARN | Very long alt text cannot be navigated; move details to the text. |
| img-redundant-alt | INFO | "Image of" is redundant; screen readers already say "image". |
| img-decorative | INFO | `alt=""` hides the image; confirm it is truly decorative. |

See `alt-text-guide.md` for how to write the text.

## Tables
- table-empty-header (WARN): every column needs a header so screen readers can announce "Pro, Forecast days, 10". Add a header such as "Feature" to the first column.
- Use tables for data, not for layout. Keep them small; split very wide tables.

## Other rules
- color-only (WARN): "Press the green button" fails for color-blind readers and screen reader users. Name the button: "Select Save (the green button)".
- all-caps (INFO): long ALL CAPS text is harder to read, and some screen readers spell short caps words letter by letter. Use normal case and bold for emphasis.
- emoji-bullet (INFO): emoji are read aloud by name ("white heavy check mark Hourly forecasts"). Use normal list markers, and keep emoji rare and meaningful.

## Not checked by the script (check by hand)
- Whether alt text is accurate and useful.
- Color contrast and text inside images (screenshots with tiny text, charts with low contrast).
- Reading order of complex layouts, and HTML blocks embedded in Markdown.
- Captions and transcripts for videos and audio.
- Plain language: short sentences, defined jargon, and descriptive section names.
FILE:templates/a11y-review.md
# Accessibility Review: <document or folder>

Date: <YYYY-MM-DD>
Files checked: <n> (<list or folder>)
Audience: <who reads these docs>
Checker run: `python3 scripts/check_md_a11y.py <paths>` -> HIGH <n>, WARN <n>, INFO <n>

## Top fixes (most impact first)
1. <fix> (<file:line>)
2. <fix>
3. <fix>

## Alt text worksheet
| File:line | Image | Purpose in the document | Current alt | New alt | Seen the image? |
|---|---|---|---|---|---|
| | | informative / functional / decorative / complex | | | yes / draft |

## Headings
- Current outline: <H1 ... / H2 ... / H4 ...>
- Proposed outline: <H1 ... / H2 ... / H3 ...>

## Links
| File:line | Current text | New text | Destination |
|---|---|---|---|
| | | | |

## Other findings
| File:line | Rule | Change |
|---|---|---|
| | | |

## After fixes
Checker rerun: HIGH <n>, WARN <n>, INFO <n> (remaining INFO items explained below).
- <INFO item: reason it is acceptable>

## Manual checks still needed
- <for example: contrast of text inside screenshots, video captions>
FILE:examples/example-readme-review.md
# Example: accessibility review of a project README

## The request
"Our open source app's README gets a lot of traffic. A user who relies on a screen reader said it is hard to follow. Can you check it and fix it? The hero image is the app on a phone with the 3-day forecast; app-main.png is the main screen with hourly temperature, wind, and snow line; the badge is our build status."

## Checker run (before)
```
$ python3 scripts/check_md_a11y.py README.md
Markdown accessibility check: 1 file(s), 3 image(s)
HIGH 2  WARN 8  INFO 5

README.md (3 images, 4 headings): 15 finding(s)
     3  HIGH  img-missing-alt          Image hero.png has empty alt text; describe it, or confirm it is purely decorative.
     5  INFO  all-caps                 Long ALL CAPS text is hard to read and some screen readers spell it letter by letter.
     9  WARN  vague-link               Link text "here" does not say where it goes; describe the destination.
     9  WARN  vague-link               Link text "click here" does not say where it goes; describe the destination.
    11  WARN  img-generic-alt          Alt text "screenshot" for app-main.png is generic; say what the image shows or why it is there.
    13  HIGH  img-no-alt               <img src="docs/img/badge.svg"> has no alt attribute.
    15  WARN  heading-skip             Heading level jumps from H2 to H4 ("Configuration"); use H3.
    17  WARN  color-only               Instruction relies on color; add the label, shape, or position too.
    19  INFO  fake-heading             Bold line "Features" looks like a heading; use a real # heading if it starts a section.
    21  INFO  emoji-bullet             Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.
    22  INFO  emoji-bullet             Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.
    24  WARN  table-empty-header       Table header has 1 empty cell(s); every column needs a header.
    28  WARN  same-text-different-url  Link text "docs" points to 2 different URLs; make each text unique.
    28  INFO  bare-url                 Bare URL https://example.org/docs; screen readers spell it out. Use [descriptive text](https://example.org/docs).
    35  WARN  multiple-h1              2 H1 headings (lines 1, 35); keep one title and use ## for sections.
```
The `![](not-an-image.png)` inside the bash code block and the inline code example on the last line were correctly ignored.

## The review (filled template, shortened)

# Accessibility Review: README.md

Audience: hikers and contributors, many arriving from search.
Checker run: HIGH 2, WARN 8, INFO 5.

### Top fixes
1. Give the hero image and the build badge real alt text (lines 3 and 13).
2. Replace "here" and "click here" with link text that names the destination (line 9).
3. Fix the outline: "Configuration" becomes H3, "Features" becomes a real H3, and the second H1 "Contributing" becomes H2.
4. Name the Save button instead of only its color (line 17).
5. Give the first table column a header (line 24).

### Alt text worksheet
| File:line | Image | Purpose | Current alt | New alt | Seen? |
|---|---|---|---|---|---|
| README.md:3 | hero.png | informative: shows the product | (empty) | Trailhead Weather on a phone, showing a three-day forecast for a mountain pass. | described by the user |
| README.md:11 | app-main.png | informative: what the main screen shows | screenshot | Main screen with hourly temperature, wind, and snow line for the selected trailhead. | described by the user |
| README.md:13 | badge.svg | informative: build status | (no alt) | Build: passing | described by the user |

### Headings
- Before: H1 Trailhead Weather / H2 Install / H4 Configuration / H1 Contributing (plus a bold "Features" line).
- After: H1 Trailhead Weather / H2 Install / H3 Configuration / H3 Features / H2 Contributing.

### Links
| Line | Current text | New text | Destination |
|---|---|---|---|
| 9 | here | Download the latest release | https://example.org/releases |
| 9 | click here | setup guide | docs/guides/setup.md |
| 28 | docs (bare URL + "docs") | API reference | https://example.org/docs |
| 28 | docs | setup guide | docs/guides/setup.md |

### Other findings
| Line | Rule | Change |
|---|---|---|
| 5 | all-caps | Normal case inside the bold note. |
| 17 | color-only | "Select Save (the green button at the bottom of Settings)". |
| 21-22 | emoji-bullet | Normal "-" list items. |
| 24 | table-empty-header | First column header "Feature". |

### Corrected README (excerpt)
```markdown
# Trailhead Weather

![Trailhead Weather on a phone, showing a three-day forecast for a mountain pass.](docs/img/hero.png)

Trailhead Weather shows mountain forecasts for hikers. **Note: this project is still in beta and things will break often.**

## Install

[Download the latest release](https://example.org/releases), or follow the [setup guide](docs/guides/setup.md).

<img src="docs/img/badge.svg" width="90" alt="Build: passing">

### Configuration

Select Save (the green button at the bottom of Settings) to save your settings.

### Features

- Hourly forecasts
- Avalanche bulletins

| Feature | Free | Pro |
|---|---|---|
| Forecast days | 3 | 10 |
```

### After fixes
```
$ python3 scripts/check_md_a11y.py README-fixed.md
Markdown accessibility check: 1 file(s), 3 image(s)
HIGH 0  WARN 0  INFO 0
```

### Manual checks still needed
- The hero image has small text on the phone screen; the alt text carries the key message, so that is fine here.
- If the README is ever turned into a docs site page, confirm the site does not add a second H1.

## Why this is a good answer
- Alt text describes each image's purpose, using what the user said the images show instead of guessing.
- Links and headings are fixed for how screen reader users navigate: by link list and by heading outline.
- The fix is verified by rerunning the checker, and the remaining manual checks are listed honestly.
FILE:scripts/check_md_a11y.py
#!/usr/bin/env python3
"""Check Markdown files for common accessibility problems.

Usage:
  python3 check_md_a11y.py README.md docs/            # files and folders (*.md, *.markdown)
  python3 check_md_a11y.py docs/ --json
  cat page.md | python3 check_md_a11y.py -
  python3 check_md_a11y.py docs/ --fail-on warn      # exit 1 on WARN too (for CI)

Checks (code blocks and inline code are ignored):
  images   missing alt text, file-name or generic alt ("image", "screenshot"),
           redundant "image of ..." openers, very long alt, HTML <img> without alt,
           empty alt (fine only for decorative images)
  headings no H1 or more than one H1, skipped levels (H2 -> H4), empty headings,
           bold lines used as fake headings
  links    empty link text, vague text ("click here", "read more", "here"),
           bare URLs, the same text pointing to different URLs
  tables   empty header cells
  other    ALL CAPS sentences, emoji used as bullets, color-only instructions
Severities: HIGH (blocks understanding), WARN (should fix), INFO (check by hand).
Exit code: 0 no HIGH, 1 HIGH found (or WARN with --fail-on warn), 2 usage error.
Standard library only.
"""
import argparse
import json
import os
import re
import sys

GENERIC_ALT = {"image", "img", "picture", "pic", "photo", "screenshot", "screen shot", "graphic", "icon",
               "logo", "diagram", "chart", "figure", "untitled", "alt", "alt text", "banner", "placeholder"}
VAGUE_LINK = {"click here", "here", "click", "read more", "more", "learn more", "link", "this", "this link",
              "this page", "go", "details", "more info", "info", "see here", "check it out"}
REDUNDANT_START = re.compile(r"^(an? )?(image|picture|photo|screenshot|graphic) (of|showing)\b", re.I)
FILE_ALT = re.compile(r"^[\w\-. ]+\.(png|jpe?g|gif|svg|webp|bmp|tiff?)$|^(img|image|dsc|screenshot)[_\- ]?\d+", re.I)
IMG_MD = re.compile(r"!\[([^\]]*)\]\(\s*<?([^)\s>]*)>?(?:\s+\"[^\"]*\")?\s*\)")
IMG_REF = re.compile(r"!\[([^\]]*)\]\[[^\]]*\]")
LINK_MD = re.compile(r"(?<!!)\[([^\]]*)\]\(\s*<?([^)\s>]*)>?(?:\s+\"[^\"]*\")?\s*\)")
HTML_IMG = re.compile(r"<img\b[^>]*>", re.I)
BARE_URL = re.compile(r"(?<![(<\"'=\[])\bhttps?://[^\s)>\]]+")
COLOR_ONLY = re.compile(r"\b(click|press|tap|select|choose|use)\b[^.]{0,30}\b(red|green|blue|yellow|orange|purple)\b(?! *\()", re.I)
EMOJI_BULLET = re.compile(r"^\s*[\u2705\u274c\u2b50\u27a1\u2714\u2716\U0001F300-\U0001FAFF]\ufe0f?\s+\S")


def strip_inline_code(line):
    return re.sub(r"`+[^`]*`+", lambda m: " " * len(m.group(0)), line)


def check_text(text, name):
    findings = []

    def add(sev, line, rule, msg):
        findings.append({"file": name, "line": line, "severity": sev, "rule": rule, "message": msg})

    lines = text.replace("\r\n", "\n").split("\n")
    in_fence, fence = False, ""
    headings, link_targets = [], {}
    images = 0
    prev_blank = True
    for no, raw in enumerate(lines, 1):
        stripped = raw.strip()
        m = re.match(r"^\s{0,3}(`{3,}|~{3,})", raw)
        if m:
            if not in_fence:
                in_fence, fence = True, m.group(1)[0] * 3
            elif stripped.startswith(fence):
                in_fence = False
            continue
        if in_fence or raw.startswith("    ") and prev_blank and not stripped.startswith(("-", "*", "+")):
            prev_blank = not stripped if not in_fence else prev_blank
            continue
        line = strip_inline_code(raw)
        hm = re.match(r"^\s{0,3}(#{1,6})(\s+|$)(.*?)\s*#*\s*$", line)
        if hm:
            level, title = len(hm.group(1)), hm.group(3).strip()
            headings.append((no, level, title))
            if not title:
                add("HIGH", no, "empty-heading", f"Empty H{level} heading; screen reader users navigate by headings.")
        elif re.fullmatch(r"\s*(\*\*|__)[^*_]{2,80}(\*\*|__):?\s*", line) and prev_blank:
            add("INFO", no, "fake-heading", f"Bold line \"{stripped.strip('*_:')}\" looks like a heading; use a real # heading if it starts a section.")
        images += len(IMG_MD.findall(line)) + len(IMG_REF.findall(line)) + len(HTML_IMG.findall(line))
        for alt, src in IMG_MD.findall(line):
            check_alt(add, no, alt, src)
        for alt in IMG_REF.findall(line):
            check_alt(add, no, alt, "(reference)")
        for tag in HTML_IMG.findall(line):
            am = re.search(r"\balt\s*=\s*(\"([^\"]*)\"|'([^']*)'|(\S+))", tag, re.I)
            src = re.search(r"\bsrc\s*=\s*[\"']?([^\"'\s>]+)", tag, re.I)
            src = src.group(1) if src else "?"
            if not am:
                add("HIGH", no, "img-no-alt", f"<img src=\"{src}\"> has no alt attribute.")
            else:
                check_alt(add, no, am.group(2) if am.group(2) is not None else (am.group(3) if am.group(3) is not None else am.group(4)), src, html=True)
        no_images = IMG_MD.sub(" ", line)
        for text_, url in LINK_MD.findall(no_images):
            label = re.sub(r"[*_`]", "", text_).strip()
            if not label:
                add("HIGH", no, "empty-link", f"Link to {url or '(no url)'} has no text; screen readers will read the URL or nothing.")
            elif label.lower().rstrip(".!:") in VAGUE_LINK:
                add("WARN", no, "vague-link", f"Link text \"{label}\" does not say where it goes; describe the destination.")
            elif re.fullmatch(r"https?://\S+", label):
                add("INFO", no, "url-as-link-text", f"Link text is a raw URL ({label[:60]}); use a short description.")
            if label:
                link_targets.setdefault(label.lower(), {}).setdefault(url, no)
        for url in BARE_URL.findall(LINK_MD.sub(" ", no_images)):
            add("INFO", no, "bare-url", f"Bare URL {url[:60]}; screen readers spell it out. Use [descriptive text]({url[:40]}).")
        if "|" in line and re.match(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$", line) and no > 1:
            header = lines[no - 2].strip().strip("|")
            cells = [c.strip() for c in header.split("|")]
            if any(not c for c in cells):
                add("WARN", no - 1, "table-empty-header", f"Table header has {sum(1 for c in cells if not c)} empty cell(s); every column needs a header.")
        run = longest = 0
        for w in re.findall(r"[A-Za-z]+", line):
            run = run + 1 if w.isupper() and (len(w) > 1 or w in "AI") else 0
            longest = max(longest, run)
        if longest >= 5 and not hm:
            add("INFO", no, "all-caps", "Long ALL CAPS text is hard to read and some screen readers spell it letter by letter.")
        if EMOJI_BULLET.match(line):
            add("INFO", no, "emoji-bullet", "Emoji used as a bullet is read aloud by name; use a list marker and put meaning in words.")
        cm = COLOR_ONLY.search(line)
        if cm:
            between = line[cm.end(1):cm.start(2)]
            inside_parens = line[:cm.start(2)].count("(") > line[:cm.start(2)].count(")")
            names_label = re.match(r"\s+(\*\*|\"|')?[A-Z]", between)  # "Select Save ..." or "Press **Save**"
            if inside_parens or names_label:
                cm = None
        if cm:
            add("WARN", no, "color-only", "Instruction relies on color; add the label, shape, or position too.")
        prev_blank = not stripped

    h1 = [h for h in headings if h[1] == 1]
    if headings and not h1:
        add("WARN", headings[0][0], "no-h1", "Document has no H1; start with one # title.")
    if len(h1) > 1:
        add("WARN", h1[1][0], "multiple-h1", f"{len(h1)} H1 headings (lines {', '.join(str(h[0]) for h in h1)}); keep one title and use ## for sections.")
    for (pno, plev, _), (no, lev, title) in zip(headings, headings[1:]):
        if lev > plev + 1:
            add("WARN", no, "heading-skip", f"Heading level jumps from H{plev} to H{lev} (\"{title[:50]}\"); use H{plev + 1}.")
    if not headings and len([l for l in lines if l.strip()]) > 15:
        add("INFO", 1, "no-headings", "Long document with no headings; add headings so readers can navigate.")
    for label, targets in link_targets.items():
        if len(targets) > 1 and label not in VAGUE_LINK:
            first = min(targets.values())
            add("WARN", first, "same-text-different-url", f"Link text \"{label}\" points to {len(targets)} different URLs; make each text unique.")
    order = {"HIGH": 0, "WARN": 1, "INFO": 2}
    findings.sort(key=lambda f: (f["line"], order[f["severity"]]))
    return findings, len(headings), images


def check_alt(add, no, alt, src, html=False):
    a = alt.strip()
    base = os.path.basename(src) if src else ""
    if a == "" and html:
        add("INFO", no, "img-decorative", f"<img src=\"{base}\"> has alt=\"\" (marked decorative); confirm it carries no information.")
        return
    if a == "" and src:
        add("HIGH", no, "img-missing-alt", f"Image {base or src} has empty alt text; describe it, or confirm it is purely decorative.")
        return
    low = a.lower().rstrip(".")
    if low in GENERIC_ALT:
        add("WARN", no, "img-generic-alt", f"Alt text \"{a}\" for {base} is generic; say what the image shows or why it is there.")
    elif FILE_ALT.search(a) or (base and low == os.path.splitext(base)[0].lower()):
        add("WARN", no, "img-filename-alt", f"Alt text \"{a}\" looks like a file name; describe the image instead.")
    elif REDUNDANT_START.match(a):
        add("INFO", no, "img-redundant-alt", f"Alt text starts with \"{' '.join(a.split()[:3])}\"; screen readers already say 'image', so start with the content.")
    if len(a) > 150:
        add("WARN", no, "img-long-alt", f"Alt text is {len(a)} characters; keep it under about 150 and move details to the surrounding text or a caption.")


def collect(paths):
    files = []
    for p in paths:
        if p == "-":
            files.append("-")
        elif os.path.isdir(p):
            for root, dirs, names in os.walk(p):
                dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d != "node_modules")
                files += [os.path.join(root, n) for n in sorted(names) if n.lower().endswith((".md", ".markdown"))]
        elif os.path.isfile(p):
            files.append(p)
        else:
            raise FileNotFoundError(p)
    return files


def main():
    ap = argparse.ArgumentParser(description="Markdown accessibility checker")
    ap.add_argument("paths", nargs="+", help="Markdown files, folders, or - for stdin")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--fail-on", choices=["high", "warn"], default="high")
    args = ap.parse_args()
    try:
        files = collect(args.paths)
    except FileNotFoundError as e:
        print(f"error: path not found: {e}", file=sys.stderr)
        return 2
    if not files:
        print("error: no Markdown files (*.md, *.markdown) found", file=sys.stderr)
        return 2
    all_findings, stats = [], []
    for f in files:
        text = sys.stdin.read() if f == "-" else open(f, encoding="utf-8", errors="replace").read()
        name = "<stdin>" if f == "-" else f
        found, nhead, images = check_text(text, name)
        stats.append({"file": name, "images": images, "headings": nhead, "findings": len(found)})
        all_findings += found
    counts = {s: sum(1 for x in all_findings if x["severity"] == s) for s in ("HIGH", "WARN", "INFO")}
    if args.json:
        print(json.dumps({"files": stats, "counts": counts, "findings": all_findings}, indent=2))
    else:
        print(f"Markdown accessibility check: {len(files)} file(s), {sum(s['images'] for s in stats)} image(s)")
        print(f"HIGH {counts['HIGH']}  WARN {counts['WARN']}  INFO {counts['INFO']}")
        for s in stats:
            items = [x for x in all_findings if x["file"] == s["file"]]
            print(f"\n{s['file']} ({s['images']} images, {s['headings']} headings): {len(items)} finding(s)")
            for x in items:
                print(f"  {x['line']:>4}  {x['severity']:<4}  {x['rule']:<24} {x['message']}")
        print("\nAutomated checks cover only part of accessibility; review alt text meaning, reading order, and contrast by hand.")
    bad = counts["HIGH"] + (counts["WARN"] if args.fail_on == "warn" else 0)
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: srt-subtitle-quality-checker
description: Checks SRT and WebVTT subtitle files for broken or overlapping timings, numbering gaps, empty cues, reading speed above a characters-per-second limit, long or extra lines, cues that flash by or linger, unbalanced tags, and sound labels, then rewrites and retimes the problem cues and can shift the whole file. Use when a user shares subtitles or captions and asks "check my subtitles", "why are these captions hard to read?", "fix the timing", or "make these subtitles follow the guidelines".
---

# SRT Subtitle Quality Checker

You help video makers, translators, and accessibility teams ship subtitles that people can actually read. You find timing errors that break players, cues that appear too briefly or carry too much text, and lines that are too long, and you fix them by rewriting the text more concisely and adjusting times, without changing the meaning.

## Files in this skill

- `scripts/check_subtitles.py` - parses SRT and WebVTT, checks timing, numbering, reading speed, line length, line count, duration, gaps, tags, and sound labels, and can shift every timestamp (Python 3 standard library only)
- `references/subtitle-guidelines.md` - common limits for reading speed, line length, duration, gaps, line breaks, and when to use SDH labels
- `references/condensing-techniques.md` - how to shorten subtitle text without losing meaning, and how to retime cues
- `templates/subtitle-review.md` - the review report to return
- `examples/example-workshop-video.md` - a worked review of a short tutorial video

## Workflow

### 1. Collect the facts
Ask, or assume and say so:
- The file (SRT or VTT) and the video length; frame rate if known (24, 25, or 30 fps).
- Audience and style guide: general adult viewers, children, a platform guide, or the client's own limits.
- Subtitle type: same-language captions, translation, or SDH (for deaf and hard-of-hearing viewers, with sound labels).
- Whether you may rewrite text or only retime it.

### 2. Run the checker
```bash
python3 scripts/check_subtitles.py movie.srt
python3 scripts/check_subtitles.py movie.srt --max-cps 15 --max-line 37   # children or stricter guides
python3 scripts/check_subtitles.py movie.vtt --json
python3 scripts/check_subtitles.py movie.srt --shift -1200 > movie-synced.srt   # whole file 1.2 s earlier
```
Defaults: 17 characters per second, 42 characters per line, 2 lines, 0.833 to 7 seconds on screen, 83 ms minimum gap. Pick limits from `references/subtitle-guidelines.md` to match the audience. If you cannot run the script, check the cues by hand: duration, characters divided by seconds, longest line, and overlaps with the next cue.

### 3. Fix in this order
1. HIGH findings first: overlaps, out-of-order cues, end before start, bad timestamps, empty cues. These break players or hide text.
2. Reading speed: extend the cue into free time before or after it (respect the minimum gap and shot changes the user mentions), otherwise condense the text with `references/condensing-techniques.md`, otherwise split the cue in two at a natural pause.
3. Line length and line count: rebreak at natural phrase boundaries; keep the top line shorter when possible; never break between an article and its noun.
4. Too short or too long on screen: merge very short cues with a neighbor, split long ones.
5. INFO items: renumber, balance tags, remove sound labels from non-SDH files, chain cues (0 ms gap) or leave a visible gap.
Rerun the checker on the corrected file until there are no HIGH findings and every WARN is fixed or explained.

### 4. Deliver
Fill in `templates/subtitle-review.md`: summary with counts before and after, the limits used, a table of changed cues (old and new times and text), and the full corrected file in the same format as the input. Follow the style of `examples/example-workshop-video.md`.

## Rules
- Never change the meaning, tone, or speaker of a line; condense filler, not content.
- Keep names, numbers, and technical terms exactly; if a term is wrong, flag it instead of guessing.
- Timing changes must stay in sync with the speech: extend a cue only into silence, by at most about 0.5 s before speech starts or 1 s after it ends, unless the user allows more.
- Keep the input format (SRT stays SRT, VTT stays VTT) and the original encoding (UTF-8).
- Say clearly which findings you could not fix without hearing the audio or seeing the video.
FILE:references/subtitle-guidelines.md
# Subtitle guidelines: common limits

Different broadcasters and platforms publish their own style guides. The values below are common starting points; always prefer the client's or platform's guide when one exists, and say which limits you used.

## Reading speed (characters per second, CPS)

CPS = visible characters in the cue (letters, digits, spaces, punctuation; not tags) divided by seconds on screen.

| Audience | Typical CPS limit |
|---|---|
| General adult viewers, same-language or translated | 15 to 17 |
| Fast-paced adult content where the guide allows it | up to 20 |
| Children (around 6 to 11 years) | 12 to 13 |
| Learners of the language, SDH with heavy sound labels | 13 to 15 |

Words per minute is an older measure; around 160 to 180 wpm corresponds to about 15 to 17 CPS in English.

## Line length and line count

- 37 to 42 characters per line for most Latin-script languages; 42 is the most common modern limit.
- Maximum 2 lines per cue. A third line covers the picture and is hard to read.
- Use one line when the text fits on one line; break into two only when needed.

## Duration on screen

- Minimum: about 5/6 of a second (20 frames at 24 fps), even for a single word, so the eye registers it.
- Maximum: about 7 seconds. Longer cues get reread and feel stuck; split them.

## Gaps between cues

- Chained cues: 0 ms gap is fine when the speech is continuous.
- Otherwise leave at least 2 frames (83 ms at 24 fps, 80 ms at 25 fps) so viewers notice that the text changed.
- Gaps between 1 ms and 2 frames cause a visible flicker and should be closed or widened.

## Line breaks

Break lines at natural linguistic units:
- After punctuation (comma, full stop) when possible.
- Before conjunctions (and, but, because) and prepositions.
- Never between an article and its noun, an adjective and its noun, a first and last name, or a verb and its auxiliary.
- Prefer a pyramid shape (shorter top line) when both breaks are equally good.

## Timing to speech and shots

- Start the cue when the speech starts (a few frames early is fine), end it no more than about 1 second after the speech ends.
- Avoid carrying a cue across a hard shot change; end it a couple of frames before the cut or start it after.

## SDH and captions

- Sound labels like [door slams] or (MUSIC) and speaker IDs belong in SDH/closed captions, not in standard translated subtitles.
- Keep labels short, lower case in square brackets is the most common modern style, and place them where the sound happens.

## Formatting

- Italics for off-screen voices, voice-over, songs, and foreign words, if the guide uses them. Every opening tag needs a closing tag in the same cue.
- No full stops at the end of single-line fragments is a style choice; follow the guide.
- SRT: cue number, timestamp line `00:01:02,500 --> 00:01:04,000`, text, blank line. VTT: `WEBVTT` header, optional cue id, timestamps with a dot `00:01:02.500`.
FILE:references/condensing-techniques.md
# Condensing and retiming subtitles

When a cue is too fast to read, try these in order. Stop as soon as the cue fits the limits.

## 1. Use free time first (no text change)

- Look at the gap before and after the cue. Extend the start up to about 0.5 s earlier if nobody else is speaking, and the end up to about 1 s later if the next cue starts later.
- Keep the minimum gap (2 frames) to the neighbors, or chain at 0 ms.
- Required time for a cue = characters / CPS limit. Example: 68 characters at 17 CPS need 4.0 s.

## 2. Cut filler, keep content

Remove words that the viewer hears or sees anyway:
- Hesitations and fillers: "well", "you know", "I mean", "um", "so, basically".
- Repetitions: "very, very" -> "very"; false starts.
- Greetings and names already obvious from the picture.
- Tag questions when tone is clear: "It's ready, isn't it?" -> "It's ready?" only if the meaning stays.

## 3. Use shorter forms

| Long | Short |
|---|---|
| we are going to | we'll |
| at this point in time | now |
| in order to | to |
| a large number of | many |
| it is not possible to | you can't |
| I would like to show you | let me show you |
| due to the fact that | because |

Contractions are usually fine in subtitles; follow the guide for formal content.

## 4. Simplify structure

- Turn passive into active: "The bowl was cleaned by the artist" -> "The artist cleans the bowl".
- Replace a clause with a single word when possible.
- Split one long sentence into two shorter cues at a natural pause.

## 5. Split or merge cues

- Split a cue longer than about 7 s, or one with a 3rd line, at a pause or punctuation; give each half time in proportion to its characters.
- Merge a cue under about 0.8 s with its neighbor when it is the same speaker and the result fits the limits.

## What never to cut

- Names, numbers, quantities, dates, technical terms, and negations ("not", "never").
- Words that carry the joke, the twist, or the emotion of the line.
- Information the viewer needs later in the video.

## Retiming the whole file

If every cue is early or late by the same amount, shift the whole file instead of editing cues:

```bash
python3 scripts/check_subtitles.py movie.srt --shift 1500 > movie-shifted.srt    # 1.5 s later
python3 scripts/check_subtitles.py movie.srt --shift -800 > movie-shifted.srt    # 0.8 s earlier
```

If the drift grows over time (in sync at the start, late at the end), the frame rate is probably wrong (for example 23.976 vs 25 fps); a constant shift will not fix it. Say so and ask for the frame rate of the video.
FILE:templates/subtitle-review.md
# Subtitle review: file_name

**Video:** video_title (duration, fps fps)
**Type:** translation / same-language captions / SDH
**Limits used:** cps chars/s, line chars/line, lines lines, min_dur to max_dur s on screen, gap ms minimum gap (source_of_limits)

## Summary

| | Before | After |
|---|---|---|
| Cues | | |
| HIGH | | |
| WARN | | |
| INFO | | |
| Average chars/s | | |

Main problems in one or two sentences.

## Changes

| Cue | Problem | Old time | New time | Old text | New text |
|---|---|---|---|---|---|
| | | | | | |

## Not fixed (needs audio or video)

- Cue ..., reason ...

## Notes for the editor

- Style choices made (italics, contractions, labels).
- Anything to check against the picture (shot changes, on-screen text).

## Corrected file

```
(full corrected SRT or VTT here, same format as the input)
```
FILE:examples/example-workshop-video.md
# Example: subtitle review of a short tutorial video

## User request

"Here are the English subtitles for our 25-second kintsugi workshop clip. Viewers say they can't keep up. Can you check them and fix what's wrong? General adult audience, normal subtitles, not SDH."

## Input (excerpt of interview.srt)

```
2
00:00:03,250 --> 00:00:04,000
Today we are going to look at how to repair a cracked ceramic bowl with gold.

3
00:00:03,900 --> 00:00:06,500
[HAMMER TAPPING]
First, clean the edges.

5
00:00:07,000 --> 00:00:16,000
<i>This technique is called kintsugi.
```

## Checker run

```
$ python3 scripts/check_subtitles.py interview.srt
interview.srt (SRT): 8 cues, 00:00:01,000 to 00:00:24,000, avg 16.3 chars/s, avg 2.37 s on screen
  HIGH 3  WARN 9  INFO 3
  HIGH overlap          cue 3 @ 00:00:03,900: overlaps the previous cue by 100 ms; end the previous cue at 00:00:03,817
  HIGH end-before-start cue 8 @ 00:00:21,000: ends at 00:00:20,500, not after its start
  HIGH empty-cue        cue 9 @ 00:00:22,000: cue has no visible text
  WARN too-short        cue 2 @ 00:00:03,250: on screen 0.75 s (minimum 0.83 s)
  WARN reading-speed    cue 2 @ 00:00:03,250: 102.7 chars/s (limit 17); needs 4.53 s on screen or about 64 fewer chars
  ...
```

## Review (filled template, shortened)

**Limits used:** 17 chars/s, 42 chars/line, 2 lines, 0.833 to 7 s, 83 ms gap (common general-audience values; no client guide given).

| | Before | After |
|---|---|---|
| Cues | 8 | 8 |
| HIGH | 3 | 0 |
| WARN | 9 | 0 |
| INFO | 3 | 0 |

Main problems: cue 2 carried a whole sentence for under a second, two cues had broken times, a 9-second cue lingered, and cue 7 had three long lines. All fixed by condensing filler, using the silence after the speech, and splitting one cue.

| Cue | Problem | Old time | New time | Old text | New text |
|---|---|---|---|---|---|
| 2 | 102.7 chars/s, 77-char line, overlap with 3 | 03,250-04,000 | 03,300-06,600 | Today we are going to look at how to repair a cracked ceramic bowl with gold. | Today we'll repair a cracked bowl / with lacquer and gold. |
| 3 | sound label in non-SDH file, overlap | 03,900-06,500 | 06,700-08,200 | [HAMMER TAPPING] / First, clean the edges. | First, clean the edges. |
| 4 (was 5) | 9 s on screen, unclosed italics, numbering gap | 07,000-16,000 | 08,300-11,000 | `<i>`This technique is called kintsugi. | `<i>`This technique is called kintsugi.`</i>` |
| 5 (was 6) | 0.4 s on screen | 16,000-16,400 | 16,000-16,900 | Okay. | Okay. |
| 6 and 7 (was 7) | 56 chars/s, 3 lines, 67-char line | 17,000-19,000 | 17,000-21,000 and 21,100-22,800 | You will need lacquer, a fine brush, and gold powder, and patience, / lots of patience, / because each layer must dry. | You'll need lacquer, a fine brush, / gold powder, and lots of patience. + Each layer must dry first. |
| 8 (was 8) | ends before it starts | 21,000-20,500 | 22,900-24,000 | Let's start. | Let's start. |
| 9 | empty cue | 22,000-24,000 | removed | | |

Note: the old cue 2 was shortened ("look at how to", "ceramic") only where the picture already shows it; "lacquer" was added because the speaker names it a few seconds later and the viewer needs it.

**Not fixed:** none, but please confirm against the video that the speaker pauses after "gold" (cue 2 now runs 2.6 s longer, into what looks like silence) and that "Let's start." is spoken at about 22.9 s.

Corrected file rechecked:

```
$ python3 scripts/check_subtitles.py interview-fixed.srt
interview-fixed.srt (SRT): 8 cues, 00:00:01,000 to 00:00:24,000, avg 14.5 chars/s, avg 2.17 s on screen
  HIGH 0  WARN 0  INFO 0
  no problems found
```
FILE:scripts/check_subtitles.py
#!/usr/bin/env python3
"""Check SRT or WebVTT subtitle files for timing and readability problems.

Usage:
  python3 check_subtitles.py FILE [FILE ...] [options]
  python3 check_subtitles.py - < movie.srt          (read stdin)

Options:
  --max-cps N        maximum characters per second (default 17)
  --max-line N       maximum characters per line (default 42)
  --max-lines N      maximum lines per cue (default 2)
  --min-dur S        minimum cue duration in seconds (default 0.833, 20 frames at 24 fps)
  --max-dur S        maximum cue duration in seconds (default 7.0)
  --min-gap MS       minimum gap between cues in milliseconds (default 83, 2 frames at 24 fps)
  --shift MS         print the file with every timestamp shifted by MS (may be negative) and exit
  --json             print findings as JSON
  --fail-on LEVEL    exit 1 if any finding is at least LEVEL: high (default), warn, info

Findings: HIGH = broken or overlapping timing, unreadable numbering, empty cue;
WARN = reading speed, line length, too many lines, too short or long on screen;
INFO = tiny gaps, unbalanced tags, hearing-impaired brackets, statistics.
Exit codes: 0 ok, 1 findings at or above --fail-on, 2 usage or parse error.
Python 3 standard library only.
"""
import json
import math
import re
import sys

TS = re.compile(r"^\s*(\d{1,2}:)?(\d{1,2}):(\d{2})[,.](\d{1,3})\s*-->\s*(\d{1,2}:)?(\d{1,2}):(\d{2})[,.](\d{1,3})(.*)$")
TAG = re.compile(r"</?[^>]+>|\{\\[^}]*\}")
LEVELS = {"info": 0, "warn": 1, "high": 2}


def to_ms(h, m, s, ms):
    h = int(h[:-1]) if h else 0
    return ((h * 60 + int(m)) * 60 + int(s)) * 1000 + int(ms.ljust(3, "0"))


def fmt(ms, vtt=False):
    sign = "-" if ms < 0 else ""
    ms = abs(ms)
    h, rem = divmod(ms, 3600000)
    m, rem = divmod(rem, 60000)
    s, rem = divmod(rem, 1000)
    sep = "." if vtt else ","
    return f"{sign}{h:02d}:{m:02d}:{s:02d}{sep}{rem:03d}"


def parse(text):
    """Return (cues, errors, is_vtt). Each cue: dict(index, start, end, lines, line_no)."""
    text = text.replace("\r\n", "\n").replace("\r", "\n").lstrip("\ufeff")
    is_vtt = text.lstrip().startswith("WEBVTT")
    blocks = re.split(r"\n\s*\n", text.strip("\n"))
    cues, errors = [], []
    line_no = 1
    for block in blocks:
        lines = block.split("\n")
        start_line = line_no
        line_no += len(lines) + 1
        if is_vtt and (lines[0].startswith("WEBVTT") or lines[0].startswith("NOTE") or lines[0].startswith("STYLE") or lines[0].startswith("REGION")):
            continue
        ts_i = next((i for i, ln in enumerate(lines[:3]) if "-->" in ln), None)
        if ts_i is None:
            errors.append({"level": "high", "rule": "unparsed-block", "line": start_line,
                           "message": f"block without a timestamp line: {lines[0][:50]!r}"})
            continue
        m = TS.match(lines[ts_i])
        if not m:
            errors.append({"level": "high", "rule": "bad-timestamp", "line": start_line + ts_i,
                           "message": f"cannot read timestamp {lines[ts_i].strip()!r} (expected 00:01:02,500 --> 00:01:04,000)"})
            continue
        g = m.groups()
        index = lines[0].strip() if ts_i == 1 else None
        cues.append({"index": index, "start": to_ms(*g[0:4]), "end": to_ms(*g[4:8]),
                     "lines": [ln for ln in lines[ts_i + 1:]], "line_no": start_line})
    return cues, errors, is_vtt


def visible(line):
    return TAG.sub("", line).strip()


def check(cues, errors, opts, is_vtt):
    out = list(errors)

    def add(level, rule, cue, msg):
        out.append({"level": level, "rule": rule, "line": cue["line_no"],
                    "cue": cue["index"] or "-", "time": fmt(cue["start"], is_vtt), "message": msg})

    if not is_vtt:
        expected = 1
        for c in cues:
            if c["index"] is None or not c["index"].isdigit():
                add("high", "bad-number", c, f"cue number missing or not a number: {c['index']!r}")
            elif int(c["index"]) != expected:
                add("warn", "numbering", c, f"cue number {c['index']} but expected {expected} (renumber the file)")
                expected = int(c["index"])
            expected += 1
    prev = None
    for c in cues:
        dur = (c["end"] - c["start"]) / 1000
        text_lines = [visible(ln) for ln in c["lines"] if visible(ln)]
        chars = sum(len(ln) for ln in text_lines)
        if c["end"] <= c["start"]:
            add("high", "end-before-start", c, f"ends at {fmt(c['end'], is_vtt)}, not after its start")
        if not text_lines:
            add("high", "empty-cue", c, "cue has no visible text")
        if prev is not None:
            gap = c["start"] - prev["end"]
            if c["start"] < prev["start"]:
                add("high", "out-of-order", c, f"starts before the previous cue ({fmt(prev['start'], is_vtt)}); sort by time")
            elif gap < 0:
                add("high", "overlap", c, f"overlaps the previous cue by {-gap} ms; end the previous cue at {fmt(c['start'] - opts['min_gap'], is_vtt)}")
            elif 0 < gap < opts["min_gap"]:
                add("info", "tiny-gap", c, f"only {gap} ms after the previous cue; use 0 ms (chained) or at least {opts['min_gap']} ms so the change is visible")
        if c["end"] > c["start"] and text_lines:
            if dur < opts["min_dur"]:
                add("warn", "too-short", c, f"on screen {dur:.2f} s (minimum {opts['min_dur']:.2f} s)")
            if dur > opts["max_dur"]:
                add("warn", "too-long", c, f"on screen {dur:.2f} s (maximum {opts['max_dur']:.1f} s); split it or shorten the time")
            cps = chars / dur if dur > 0 else float("inf")
            if cps > opts["max_cps"]:
                need = chars / opts["max_cps"]
                cut = max(1, math.ceil(chars - opts["max_cps"] * dur))
                add("warn", "reading-speed", c, f"{cps:.1f} chars/s (limit {opts['max_cps']:g}); needs {need:.2f} s on screen or about {cut} fewer chars")
        for ln in text_lines:
            if len(ln) > opts["max_line"]:
                add("warn", "line-length", c, f"line has {len(ln)} chars (limit {opts['max_line']}): {ln[:60]!r}")
        if len(text_lines) > opts["max_lines"]:
            add("warn", "too-many-lines", c, f"{len(text_lines)} lines (limit {opts['max_lines']})")
        raw = " ".join(c["lines"])
        for tag in ("i", "b", "u"):
            if len(re.findall(rf"<{tag}>", raw, re.I)) != len(re.findall(rf"</{tag}>", raw, re.I)):
                add("info", "unbalanced-tag", c, f"<{tag}> tags are not balanced in this cue")
        if re.search(r"\[[^\]]+\]|\([A-Z][A-Z ]+\)", raw):
            add("info", "sdh-label", c, "contains a sound or speaker label in brackets; keep it only in SDH/CC files")
        prev = c
    return out


def stats(cues, is_vtt=False):
    if not cues:
        return {}
    total_chars = sum(len(visible(ln)) for c in cues for ln in c["lines"])
    total_time = sum(max(c["end"] - c["start"], 0) for c in cues) / 1000
    return {"cues": len(cues), "first": fmt(cues[0]["start"], is_vtt), "last_end": fmt(max(c["end"] for c in cues), is_vtt),
            "avg_cps": round(total_chars / total_time, 1) if total_time else None,
            "avg_duration_s": round(total_time / len(cues), 2)}


def shift_text(text, delta):
    def rep(m):
        g = m.groups()
        vtt = "." in m.group(0).split("-->")[0]
        a = max(to_ms(*g[0:4]) + delta, 0)
        b = max(to_ms(*g[4:8]) + delta, 0)
        return f"{fmt(a, vtt)} --> {fmt(b, vtt)}{g[8]}"
    return "\n".join(TS.sub(rep, ln) if "-->" in ln else ln
                     for ln in text.replace("\r\n", "\n").split("\n"))


def main(argv):
    opts = {"max_cps": 17.0, "max_line": 42, "max_lines": 2, "min_dur": 0.833, "max_dur": 7.0,
            "min_gap": 83, "json": False, "fail_on": "high", "shift": None}
    files = []
    it = iter(argv)
    try:
        for a in it:
            if a == "--json":
                opts["json"] = True
            elif a in ("--max-cps", "--min-dur", "--max-dur"):
                opts[a[2:].replace("-", "_")] = float(next(it))
            elif a in ("--max-line", "--max-lines", "--min-gap", "--shift"):
                opts[a[2:].replace("-", "_")] = int(next(it))
            elif a == "--fail-on":
                opts["fail_on"] = next(it).lower()
                if opts["fail_on"] not in LEVELS:
                    raise ValueError("--fail-on must be high, warn, or info")
            elif a in ("-h", "--help"):
                print(__doc__)
                return 0
            elif a.startswith("--"):
                raise ValueError(f"unknown option {a}")
            else:
                files.append(a)
    except (StopIteration, ValueError) as e:
        print(f"error: {e or 'option needs a value'}", file=sys.stderr)
        return 2
    if not files:
        print("error: give at least one .srt or .vtt file, or - for stdin", file=sys.stderr)
        return 2
    report, worst = [], -1
    for f in files:
        try:
            text = sys.stdin.read() if f == "-" else open(f, encoding="utf-8-sig").read()
        except (OSError, UnicodeDecodeError) as e:
            print(f"error: cannot read {f}: {e}", file=sys.stderr)
            return 2
        if opts["shift"] is not None:
            sys.stdout.write(shift_text(text, opts["shift"]))
            return 0
        cues, errors, is_vtt = parse(text)
        if not cues:
            print(f"error: {f}: no subtitle cues found (is this an SRT or WebVTT file?)", file=sys.stderr)
            return 2
        findings = check(cues, errors, opts, is_vtt)
        for x in findings:
            worst = max(worst, LEVELS[x["level"]])
        report.append({"file": f, "format": "vtt" if is_vtt else "srt", "stats": stats(cues, is_vtt), "findings": findings})
    if opts["json"]:
        print(json.dumps(report, indent=2))
    else:
        for r in report:
            counts = {lv: sum(1 for x in r["findings"] if x["level"] == lv) for lv in ("high", "warn", "info")}
            st = r["stats"]
            print(f"{r['file']} ({r['format'].upper()}): {st['cues']} cues, {st['first']} to {st['last_end']}, "
                  f"avg {st['avg_cps']} chars/s, avg {st['avg_duration_s']} s on screen")
            print(f"  HIGH {counts['high']}  WARN {counts['warn']}  INFO {counts['info']}")
            for x in sorted(r["findings"], key=lambda x: (-LEVELS[x["level"]], x["line"])):
                where = f"cue {x.get('cue', '-')} @ {x['time']}" if "time" in x else f"line {x['line']}"
                print(f"  {x['level'].upper():<4} {x['rule']:<16} {where}: {x['message']}")
            if not r["findings"]:
                print("  no problems found")
    return 1 if worst >= LEVELS[opts["fail_on"]] else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))