AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

md-review

Use when converting a markdown code review with diff blocks and severity callouts into a two-column HTML review. Parses diffs with diff_parser.py and annotations with annotation_extractor.py; requires a named reviewer.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--md-review at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/diff_rendering_canon.md

Diff Rendering Canon

Why this exists: The md-review converter renders unified diffs into a two-column HTML layout. Diff rendering has 50 years of UI history; this document records the conventions it inherits from and where it diverges.

The convention

Unified-diff format (the --- a/file, +++ b/file, @@ -10,7 +10,8 @@ shape) is the lingua franca every modern code-review tool reads:

  • + (green tint): line added in the new version
  • - (red tint): line removed from the old version
  • (no tint): unchanged context line
  • @@ -old_start,old_count +new_start,new_count @@ optional_context: hunk header
  • \ No newline at end of file: meta line (rendered italic, no color)

md-review honors this exactly. The renderer assigns per-line numbers on both the old side (lo) and the new side (ln), with a clear visual separation by border.

Color discipline

WCAG 1.4.1 (Use of Color) requires that color must not be the sole signal. Our diff rendering uses:

  • Tint backgrounds (color-mix(in srgb, var(--md-success) 15%, transparent) for additions; color-mix(... --md-warn 12% ...) for deletions) — derived from the design-system palette, so they automatically follow the user's brand and stay within WCAG-validated contrast on the user's chosen bg.
  • Mark column (+ / − / ) — visible character, redundant with the color, screen-reader-skipped via aria-hidden="true".
  • Line numbers in both columns — provides spatial grounding independent of color.

Result: a deuteranopic reader (red-green color blindness) still distinguishes additions from deletions via the mark column and line-number columns.

What we deliberately don't do

  • Syntax highlighting inside diffs — Prism.js doesn't track per-line edits well, and conflicting addition/deletion backgrounds + token colors produce noisy output. Plain monospace is more legible. (Engineers reviewing diffs spend most attention on the change itself, not the surrounding language.)
  • Word-level diffing — difftastic-style intra-line highlighting is great for tiny edits but ambiguous for refactors. We render whole lines and let the reader compare them visually.
  • Inline-reply threading — md-review is a generator (markdown → HTML); it produces an artifact, not a thread. For threaded discussion, use the host platform (GitHub PR comments, GitLab discussions).
  • Split-pane (old | new) view — the convention this converter targets is the unified diff (sequential, single column), because that's what gets pasted into markdown review notes. Split-pane is a tool for active reviewing in an IDE.

Sources

1. POSIX diff -u (Single Unix Specification, c. 1990)

The format spec. The @@ -A,B +C,D @@ hunk header, the +/-/ prefixes, the --- a/ / +++ b/ file headers — all defined here. Every tool that follows reads the same shape.

2. GitHub PR diff view

The reference UI for two decades. Established:

  • Per-line line numbers on both old and new sides
  • Tinted backgrounds for additions/deletions
  • File-header sticky bar
  • Hunk separator with grey background We mirror the convention; we don't reinvent it.

3. GitLab MR diff view

Same convention as GitHub, with one small refinement: the per-hunk @@ header context (the function name after the @@) is rendered as a sticky element so the reader knows what function they're in. We render this header context in the hunk-head bar.

4. difftastic — semantic diff tool (github.com/Wilfred/difftastic)

Argues for AST-aware intra-line diffing instead of line-based. We acknowledge the case but rejected it for two reasons: (1) parsing every language is out of scope; (2) most agent-generated review markdown contains a few short hunks, where intra-line diff adds noise more than signal.

5. Software Engineering at Google — Tom Manshreck & Hyrum Wright (O'Reilly, 2020), Ch. 9 "Code Review"

The discipline around how diffs get read. Three claims used here:

  • "Reviewers spend most of their attention on a few hunks, not all of them" → jump-nav at top is essential
  • "Comments must reference a specific line" → annotations are attached to hunks, not free-floating
  • "Approval should be explicit and recorded" → LGTM markers are surfaced as the approval bar

6. Google Code Review Developer Guide (google.github.io/eng-practices/review/reviewer)

The taxonomy of severity (blocker, must-fix, nice-to-have, nit) maps to our default BLOCKER / MAJOR / MINOR / NIT convention. The phrase "nit:" specifically is from Google's recommended review vocabulary.

7. GitHub Markdown — fenced code blocks with language hints (```diff)

The convention this converter targets. Agent-generated review markdown wraps every diff in ```diff, which becomes our extraction grammar in diff_parser.py.

Applied to md-review

diff_parser.py extracts the hunks from ```diff fenced blocks. review_html_renderer.py lays them out in the standard unified-diff shape, with the addition/deletion coloring derived from the design-system palette so reviews look on-brand without losing the universal color convention.