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

```bash
# 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")
- **2-column hunk rows** — unified diff on the left (per-line old/new line numbers, +/− marks, addition/deletion background tint from design-system tokens), annotation cards on the right (color + icon + aria-label per WCAG 1.4.1)
- **Approval bar** — if `LGTM` markers are present and no severity annotations, a success-tinted "LGTM — no findings flagged" bar
- **General comments** — annotations not attached to any hunk render at the bottom in their own section
- **Reviewer footer** — mandatory; refuses to render without `--reviewer`
- **Responsive** — 2-col collapses to stacked on viewports < 900px

## Hard rules

1. **`--reviewer` is mandatory.** A code review must name a human reviewer. Refuses with exit 3 otherwise. Mirrors research-ops's "named owner" discipline.
2. **Refuses if no hunks present.** No `--- a/file` + `@@ ... @@` blocks means this isn't a code review — refuses with exit 4 and recommends `md-document`.