| 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
python3 markdown-html/skills/md-review/scripts/diff_parser.py \
--input <path>.md --output hunks.json
python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
--input <path>.md --diff-blocks hunks.json --output annotations.json
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")
