alirezarezvani/md-review
markdown-html/skills/md-review/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add alirezarezvani/claude-skills md-reviewInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jul 2, 2026, 4:31 AM204.4s7 files scanned
SKILL.md
- 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")
- 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)
Related Skills
alirezarezvani/weekly-review
development
VerifiedTrustedCommunity
Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/meetings
development
VerifiedTrustedCommunity
Use when someone wants to decide whether a meeting is worth calling, price a meeting in dollars, build a timeboxed agenda with desired outcomes, or turn messy meeting notes into owned action items — or says "should this be a meeting", "/cs:meeting-prep", or "/cs:meeting-actions". Runs a cost gate (ASYNC / NOT-READY / MEET), builds a decision-first agenda, and extracts an owner + due-date checklist that flags every orphan.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/fable-goal
development
VerifiedTrustedCommunity
Convert a rambling description of a desired outcome into one polished, autonomous /goal prompt ready to paste into a fresh session. Use when the user says "/fable-goal", "turn this into a goal prompt", "write me a fable prompt", "write the prompt that builds X", or rambles about something they want made and asks for the prompt that makes it happen. The output is a single copy-paste prompt, never the build itself. Do NOT use when the user wants the thing built right now in this session — only when they want the PROMPT that will make it happen in a fresh session.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/deep-work
development
VerifiedTrustedCommunity
Use when someone wants to plan a deep work day, time-block their calendar or task list, budget or cut shallow work, protect focus hours, track deep-work sessions and streaks, run an end-of-day shutdown ritual, or says "/deep-work" or "/time-block". Classifies tasks deep vs shallow, builds an energy-first time-blocked schedule that refuses deep demand past the 4-hour ceiling, batches shallow work into at most two windows, and logs focus sessions against a weekly target.
22,702SKILL.mdUpdated Jul 18, 2026