md-review
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.
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- md-review
- tags
- [ "markdown", "html", "code-review", "diff", "severity", "annotations", "single-file", "design-system", "wcag-1.4.1" ]
- author
- Alireza Rezvani
- license
- MIT
- version
- 2.10.2
- 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.
- compatible_tools
- [ "claude-code", "codex-cli", "cursor", "antigravity", "opencode", "gemini-cli" ]
03 SKILL.md 正文
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")
- 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
LGTMmarkers 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
--revieweris mandatory. A code review must name a human reviewer. Refuses with exit 3 otherwise. Mirrors research-ops's "named owner" discipline.- Refuses if no hunks present. No
--- a/file+@@ ... @@blocks means this isn't a code review — refuses with exit 4 and recommendsmd-document. - Refuses input < 100 lines. Markdown wins below the threshold (Shihipar).
- Refuses without onboarding. Same gate as every converter.
- Severity is never color-only. Each badge ships color + icon +
aria-label+ text. WCAG 1.4.1 enforced at the renderer level. - Single-file output. All CSS inline. Only external is Google Fonts CSS. No Prism in md-review (diff coloring conflicts with syntax highlighting).
- Custom severity convention.
--severity-convention "critical,important,suggestion,nit"swaps tier names; position 0 is most severe. Default is BLOCKER / MAJOR / MINOR / NIT (Google Code Review Developer Guide).
Forcing-question library (Matt Pocock grill discipline)
- Who is the named reviewer? Recommended: the user signing off on the review. Canon: research-ops named-owner pattern; SWE at Google ch. 9.
- Which severity convention applies — default (BLOCKER/MAJOR/MINOR/NIT) or custom? Recommended: default unless your team has a documented alternative. Canon: Google Code Review Developer Guide.
- Are annotations anchored to specific hunks, or are some general? Recommended: anchor everything you can; general goes to the unanchored section. Canon: SWE at Google ch. 9 — "Comments must reference a specific line".
- What's the PR title for the
<title>and header? Recommended: the actual PR / commit title. Canon: docs-as-context-for-readers. - Should
LGTMmarkers ship as the approval bar? Recommended: yes if there are no severity annotations; otherwise the findings take precedence.
Distinct from
md-document— that converter renders prose + tables + code + callouts. This one renders diff hunks + margin annotations.md-slides— that converter splits on---boundaries. This one is a single-page artifact.- GitHub PR comments — those are a thread. This is a single-author snapshot artifact.
Output artifact
{default_output_dir}/review-{slug}.html (path resolved by orchestrator's output_path_resolver.py; collision suffix -2, -3, … by default).
References
- Shihipar — Claude Code HTML output (Medium, 2026), Tier 2 use case
- Software Engineering at Google (Manshreck & Wright, O'Reilly 2020), ch. 9 "Code Review"
- Google Code Review Developer Guide — severity convention source
- WCAG 2.2 §1.4.1 — color-not-sole-signal enforcement
- See
references/for full citations (diff_rendering_canon, severity_coding, pr_annotation_ux)
04 同仓库更多 Skills
webmcpify
Make a web app agent-ready — propose a WebMCP tool manifest, integrate, verify in a real browser, heal; unrelated code stays untouched. Use for "webmcpify", "add WebMCP", or "expose app actions to AI agents".
vardoger-analyze
Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'.
transloadit-media-processing
Process media files (video, audio, images, documents) using Transloadit. Use when asked to encode video to HLS/MP4, generate thumbnails, resize or watermark images, extract audio, concatenate clips, add subtitles, OCR documents, or run any media processing pipeline. Covers 86+ processing robots for file transformation at scale.
terraform-azurerm-set-diff-analyzer
Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes. Use when reviewing terraform plan output for Azure resources like Application Gateway, Load Balancer, Firewall, Front Door, NSG, and other resources with Set-type attributes that cause spurious diffs due to internal ordering changes.
technical-job-search
Use this skill when a software engineer asks for help with job search tasks: parsing or analyzing a job description, tailoring a CV/resume, writing a cover letter, evaluating a job offer, or drafting a post-interview follow-up email. Do not activate for general career advice unrelated to an active job search action.
steno-mode
Shorthand-first response compression that cuts ~40% of response tokens while preserving technical precision and exact literals. Use when the user says "steno mode", "shorthand mode", "compressed responses", "token reduction", "brief structured output", or invokes /steno. Supports four compression levels: lite, brief, court, machine. Do not trigger for requests needing polished prose such as onboarding/tutorial content, stakeholder or customer-facing copy, or teaching-focused explanations.