` rows with an optional `note_md` for a one-paragraph summary.
- The warm palette, the serif headings, the risk-map chips with anchor highlighting, the suggestions checklist.
- Mermaid is the only CDN dependency, loaded only when the spec carries `diagrams`.
### 5. Validate every Mermaid diagram before saving
A Mermaid diagram with a syntax error degrades silently: the reader sees an empty area or a literal code block where the diagram should be, and that's a worse outcome than no diagram at all. Validate every `` block before you consider the artifact done. Don't trust visual inspection of the source -- corner cases like `:=`, unquoted labels with parentheses, and `
` in node labels parse in some diagram types and not others.
For each diagram, extract the body and run it through `mmdc`:
```python
import re, subprocess, tempfile
from pathlib import Path
def validate_mermaid_in(html_path: Path) -> list[tuple[int, str]]:
text = html_path.read_text()
failures = []
for idx, m in enumerate(re.finditer(r'(.*?)
', text, re.S)):
body = m.group(1).strip()
with tempfile.NamedTemporaryFile("w", suffix=".mmd", delete=False) as f:
f.write(body)
tmp = f.name
proc = subprocess.run(["mmdc", "-i", tmp, "-o", tmp + ".svg"], capture_output=True, text=True)
if proc.returncode != 0:
failures.append((idx, proc.stderr.splitlines()[-1] if proc.stderr else "unknown error"))
return failures
```
Alternatively, use the [mermaid skill](../mermaid/SKILL.md) (`skills/mermaid/scripts/validate_mermaid.py`) which wraps the same call with nicer error reporting and supports the `beautiful-mermaid` renderer when available.
If a diagram fails, fix it (see the mermaid skill for syntax fixes) and revalidate. If a diagram cannot be made to validate, fall back to plain text or remove it entirely. Shipping a broken diagram is not an option.
For diagrams that should also be eyeballed (call graphs, request paths -- anything where layout matters), render to SVG with `mmdc -i tmp.mmd -o tmp.svg` and open the SVG. Mermaid's auto-layout sometimes produces overlapping edges or cramped nodes; fix the layout via direction hints (`flowchart LR` vs `TB`) or by simplifying the node labels.
### 6. Save and surface the output
Save to `./review-artifacts/--.html` (create the directory if missing). Use a slug that names the head branch, a PR number if the user supplied one, or the module being explained -- `auth-refactor-review.html`, `pr-1247-writeup.html`, `auth-flow-understanding.html`. Print the absolute path so the user can open it with `open ` or `xdg-open `.
If you produced more than one artifact, list each path and what it contains in a short final summary (two or three lines is plenty).
## Pitfalls to avoid
- **Fabricated line numbers.** Always cite line numbers from the actual file you read, not from the diff hunk header (which counts post-change file lines but only for that hunk). If you didn't read the file, don't cite the line.
- **Hand-rendered diffs.** Don't retype hunks from memory or from a paraphrase of the diff, and don't try to reproduce the visual chrome (severity pills, risk chips, collapsible panels) by hand. Capture `git diff ... -- ` straight into each file's `diff` field in the spec, and let `render_artifact.py` produce the HTML. Hand-built HTML is how this skill regresses on consistency between runs.
- **Reading without filtering.** A 40-file PR doesn't need 40 file panels of equal weight. The risk map exists so most files get one line ("safe, formatting only") and the interesting two or three get full treatment.
- **Dressing up the page.** Animations, custom cursors, gradient meshes, decorative fonts -- these belong in the `frontend-design` skill's marketing-page output, not here. The reader is doing work; don't get in the way.
- **One mega-artifact.** A writeup is not a review is not an understanding doc. Their audiences and purposes differ. Producing separate files keeps each one focused and shareable.
- **Diagrams that restate prose.** A Mermaid graph that lists "Step 1 → Step 2 → Step 3" next to a numbered list duplicates information. Use diagrams for branching, joining, cycles, or anything genuinely two-dimensional.
- **Unvalidated Mermaid.** Don't ship a diagram you haven't run through `mmdc`. The diagram source can look fine and still fail to parse for non-obvious reasons (a `:` in a state-diagram transition label, an unquoted parenthesis in a flowchart node, a `
` in a context that doesn't allow it). The reader gets a blank slot, not an error message; you'll never know it broke unless you validated.
- **Linking out where the reader can't follow.** Internal company URLs, JIRA tickets, and private GitHub links should be clearly labelled as such; don't pretend the reader has access.
## Quick reference: what each artifact contains
The full templates live in `references/`; this table is just orientation. The renderer's visual conventions (palette, severity colors, diff chrome) are documented separately in [references/html-conventions.md](references/html-conventions.md).
| [PR review](references/pr-review.md) | [PR writeup](references/pr-writeup.md) | [Code understanding](references/code-understanding.md) |
|-------------------------------|-----------------------------|---------------------------------|
| PR metadata header | TL;DR (2-3 sentences) | Title: "How X flows through Y" |
| Summary of what the PR does | Why (problem + impact) | Short intro + trust boundaries |
| File-level risk map | Change stats grid + per-file table | Request path / call graph (Mermaid) |
| File panels with annotated diffs | File-by-file conceptual tour | Numbered callstack walkthrough |
| Severity-tagged inline comments | Focus areas with line refs | Key files list |
| Recommendations / blocking items | Test plan, rollout / migration notes | Gotchas / non-obvious invariants |