Md Review

Markdown Review Gate

The quality gate that runs before Markdown becomes HTML. A converter will happily render a document with three H1s, four dead links, an image with no alt text, and a 67-word sentence — the HTML validates and the page is still bad. This skill catches those defects while they are still cheap to fix, and fails the build when they are blocking.

Zero network calls, by design. Relative links and anchors resolve on disk; external URLs are inventoried and reported but never fetched. A gate that fails because someone else's server was slow is a gate engineers learn to ignore.

When to use this skill

• Before publishing a doc, guide, or article that will be converted to HTML
• Wiring a docs CI gate that must block a merge on real defects without blocking on style
• Auditing an inherited Markdown corpus to size the accessibility and link-rot backlog
• Enforcing house terminology across a docs set (front-end vs frontend, GitHub vs Github)
• Checking accessibility of source content against the WCAG criteria that survive conversion
• Calibrating prose to an audience — a runbook read at 3am needs a different band than an API reference

Inputs the skill expects

• One or more Markdown files (with or without YAML frontmatter)
• A review config JSON: required frontmatter fields, structure and accessibility thresholds, term map, gate settings
• The target audience for the prose (drives the readability band — the single most consequential input)
• The project root, when the corpus uses root-relative (/docs/...) links
• The blocking policy: which severity fails the build, and the warning budget

Clarify First

Before generating, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Target audience for the prose — why it changes the output: selects the Flesch band and grade ceiling; a general-public band (60-80) and a specialist band (40-60) flag opposite sets of sentences
• Required frontmatter fields — why it changes the output: every missing field is an error, so guessing the schema produces either false blockers or a silent gap
• Blocking severity and warning budget — why it changes the output: decides whether the run reports or blocks, which determines whether this is an audit or a gate
• Whether the corpus is new or inherited — why it changes the output: an inherited corpus needs report-only phase 1, not a gate that fails on day one

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Gate a document before publication

The default path. Run all three tools; any non-zero exit blocks.

1. Pick or write a config profile (start from assets/sample_review_config.json).
2. Run the structure/frontmatter/accessibility gate.
3. Run the offline link checker.
4. Run the readability and terminology scorer.
5. Fix errors; triage warnings against the budget.

cd "$(git rev-parse --show-toplevel)"
CFG=markdown-html/md-review/assets/sample_review_config.json
DOC=markdown-html/md-review/assets/sample_article.md

python3 markdown-html/md-review/scripts/md_review_gate.py --input "$DOC" --config "$CFG" --format text
python3 markdown-html/md-review/scripts/link_checker.py --input "$DOC" --root "$PWD" --format text
python3 markdown-html/md-review/scripts/readability_scorer.py --input "$DOC" --config "$CFG" --format text

The shipped sample_article.md deliberately contains real defects, so this run exits non-zero. Swap in sample_article_clean.md to see all three pass.

Workflow 2 — Audit a corpus without blocking anything

Phase 1 of any rollout. Collect the real finding distribution before deciding what to enforce.

1. Run every file with --fail-on never so nothing exits non-zero.
2. Emit JSON and append to a single JSONL stream.
3. Rank rules by frequency; tune thresholds and the term map before switching the gate on.

cd "$(git rev-parse --show-toplevel)"
CFG=markdown-html/md-review/assets/sample_review_config.json

find markdown-html/md-review/assets -name '*.md' -print0 |
  xargs -0 -I{} python3 markdown-html/md-review/scripts/md_review_gate.py \
    --input {} --config "$CFG" --format json --fail-on never > /tmp/md_audit.jsonl

python3 -c "import json;[print(f['rule']) for l in open('/tmp/md_audit.jsonl') if l.strip().startswith('{')]" 2>/dev/null || \
  echo "inspect /tmp/md_audit.jsonl for the per-file finding arrays"

Workflow 3 — Calibrate prose to an audience

When the complaint is "nobody reads our docs" rather than "our docs are broken".

1. Score the document and read the sentence-level findings, not just the aggregate.
2. Rewrite the very-long sentences first — they dominate the score and the reader's experience.
3. Re-score and confirm the long-sentence percentage is under 10%.

cd "$(git rev-parse --show-toplevel)"
CFG=markdown-html/md-review/assets/sample_review_config.json

# Full report, including passive-voice and terminology findings
python3 markdown-html/md-review/scripts/readability_scorer.py \
  --input markdown-html/md-review/assets/sample_article.md --config "$CFG" --format text

# Readability band only — ignore terminology while rewriting sentences
python3 markdown-html/md-review/scripts/readability_scorer.py \
  --input markdown-html/md-review/assets/sample_article.md --config "$CFG" \
  --fail-on readability --no-passive --format json

Decision frameworks

Severity assignment — what earns an error [PROVEN]

A finding blocks publication only if it passes all three tests. Everything else is a warning.

Broken link, missing alt text, skipped heading level, headerless table, missing required frontmatter field → error. Long sections, terminology drift, heading capitalization, readability band → warning. Passive voice → info.

Never downgrade a11y.missing-alt. Every other rule has a defensible exception; this one does not. If an image is decorative, mark it decorative — do not suppress the rule.

Readability target bands by audience [PROVEN]

The single table that makes readability scoring useful. A score without a target audience is noise.

Only the floor blocks. Prose easier than its band is prose more people can read; the scorer records it as info. Gating both bounds teaches authors to pad sentences, which inverts the point.

The safety-critical row is the one teams get wrong. Comprehension collapses under stress — an incident runbook written at grade 12 is unreadable at 3am during an outage.

Sentence-length thresholds [PROVEN]

Target mean ≤ 20 words with ≤ 10% of sentences over 30. The percentage matters more than the mean — an 18-word average with 20% monsters reads worse than a 22-word average with none.

WCAG coverage — what source-level checks can and cannot prove [RECOMMENDED]

Run the bottom three against converted HTML. Claiming source-level checks prove WCAG conformance is how teams end up with a compliance badge on an inaccessible site.