md-review

name	md-review
description	Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review — unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing.
version	2.10.2
author	Alireza Rezvani
license	MIT
tags	["markdown","html","code-review","diff","severity","annotations","single-file","design-system","wcag-1.4.1"]
compatible_tools	["claude-code","codex-cli","cursor","antigravity","opencode","gemini-cli"]

md-review — Code-review markdown → 2-column HTML

The code-review converter from Tier 2 of Shihipar's essay ("Code Review and PR Writeups"). Takes a markdown PR writeup with diff blocks + severity callouts and produces a single-file HTML review with a jump-nav, 2-column diff + annotation layout, and a named reviewer footer.

Three stdlib tools pipeline together:

diff_parser.py  →  annotation_extractor.py  →  review_html_renderer.py
   (md → diff hunks)   (md → severity-tagged    (hunks + annotations
                        annotations attached     + tokens → 2-col HTML)
                        to nearest hunk)

When to invoke

Symptom	Action
markdown-html-orchestrator routes input as REVIEW	Invoke this skill
User runs /cs:md-review <path>.md directly	Invoke this skill
Input contains ```diff fenced blocks + > [!MAJOR]/> [!BLOCKER]/etc. callouts	Invoke this skill
Input is a long-form spec / report (no diff blocks)	Route to md-document instead
Input is a slide deck	Route to md-slides instead
Input < 100 lines	Refuse (Shihipar threshold)
Design-system not onboarded	Refuse; surface /cs:design-system

Pipeline

# 1. Parse markdown → diff hunks JSON
python3 markdown-html/skills/md-review/scripts/diff_parser.py \
    --input <path>.md --output hunks.json

# 2. Extract severity-tagged annotations, attach to nearest preceding hunk
python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
    --input <path>.md --diff-blocks hunks.json --output annotations.json

# 3. Render 2-col HTML (--reviewer is mandatory — refuses without)
python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
    --diff-blocks hunks.json --annotations annotations.json \
    --reviewer "Jane Doe" --title "PR #123: Add retry logic" \
    --output review.html

What gets rendered

• Top jump-nav — every annotation with severity badge + 80-char preview + jump link; severity counts in the heading ("3 BLOCKER · 2 MAJOR · 1 NIT")