html-effectiveness-review

02-review — Code review and understanding

"Diffs and call-graphs are spatial information; markdown flattens them. Let the agent render the change as an annotated diff, draw the module as boxes and arrows, or write the PR description your reviewers actually want."

When to use

User says	Which paradigm to use	Template
"review this PR / review #312"	PR review (reviewer perspective)	`../../templates/diff.html`
"help me write a PR description / write a PR writeup"	PR writeup (author perspective)	`../../templates/pr.html`
"how does X work in this repo / what is the call stack"	Module diagram	Self-built (see below)
"explain the auth flow / how does sync work"	Module diagram	Same as above

Paradigm 2.1 · PR review (reviewer perspective)

Spatial shape：

Top: one-sentence summary + file risk map(one dot per file, color = risk, size = change volume)
File list: one collapsible section per file; heading includes risk badge + diff line count; expand to see diff with line numbers
Line-numbered diff must bemonospace-aligned

3 levels of risk labels(do not subdivide further, users cannot remember):

safe — pure additions / type extensions / tests → green
worth a look — minor behavior changes / refactoring → yellow
needs attention — critical paths / new abstractions / error-prone points → red

HTML skeleton：

<header class="pr-summary">
  <h1>PR #247 — Review Summary</h1>
  <p>[一句话: what this PR does]</p>
</header>

<section class="risk-map">
  <h2>Risk map</h2>
  <svg viewBox="0 0 600 120">
    <g><circle cx="60"  cy="60" r="14" class="needs-attn" />
       <text x="60" y="95" text-anchor="middle">useOptimisticTasks.ts</text></g>
    <g><circle cx="160" cy="60" r="20" class="worth" />
       <text x="160" y="95" text-anchor="middle">TaskList.tsx</text></g>
    <!-- ... 圆点大小 = LOC log；位置随便排但保持视觉密度 -->
  </svg>
</section>

<section class="files">
  <details open>
    <summary>
      <code>src/hooks/useOptimisticTasks.ts</code>
      <span class="badge danger">needs attention</span>
      <span class="muted">+58 −0</span>
    </summary>
    <pre class="diff"><div class="line added"><span class="ln">12</span><span>+ ...</span></div></pre>
  </details>
</section>

Key CSS(diff line numbers):

.diff { font-family: var(--font-mono); font-size: 12.5px; line-height: 1.55; }
.diff .line { display: grid; grid-template-columns: 56px 1fr; gap: 0; }
.diff .ln { color: var(--gray-500); padding: 0 12px; text-align: right;
            background: var(--gray-100); user-select: none; }
.diff .added   { background: rgba(120, 140, 93, 0.12); }
.diff .removed { background: rgba(176, 74, 74, 0.10); }

shared/base.css already includes the above classes, use directly.

Ready-to-use template：../../templates/diff.html

Paradigm 2.2 · PR writeup (author perspective)

Spatial shape: 6 sections, arranged in the reviewer's reading order:

TL;DR box — motivation and result covered in one paragraph
Why — why the previous approach did not work
Before / After — two-column comparison, 4 items vs 4 items
File-by-file — in suggested reading order, each file collapsible
Where to focus — numbered 1/2/3, each says "look here because of what", includes "what I deliberately did NOT do"
Test plan — four groups: unit / integration / staging / manual
Rollout — Day 0 / Day 2 / Day 4 ladder

Key CSS(rollout ladder):

ol.ramp { list-style: none; padding: 0; display: grid;
          grid-template-columns: repeat(3, 1fr); gap: 12px; }
ol.ramp li { padding: 16px 18px; background: var(--white);
             border: 1px solid var(--gray-300); border-radius: 10px;
             display: flex; flex-direction: column; gap: 4px; }
ol.ramp .pct { font-size: 22px; font-weight: 500; color: var(--clay); }

Ready-to-use template：../../templates/pr.html

Paradigm 2.3 · Module diagram / Code Understanding

Spatial shape：

Top: request path SVG (boxes + arrows), highlighting the hot path
Below: numbered 1/2/3/4/5 callstack
- Each step: file name + line number + a paragraph of explanation in Chinese and English + <details> collapsed source code

Key CSS：

.callstack li { display: grid; grid-template-columns: 32px 1fr; gap: 16px;
                margin-bottom: 24px; list-style: none; }
.callstack .num { width: 32px; height: 32px; border-radius: 50%;
                  background: var(--clay); color: white; display: grid;
                  place-items: center; font-weight: 600;
                  font-family: var(--font-mono); }
.callstack .file { font-family: var(--font-mono); font-size: 13px;
                   color: var(--gray-700); }
.callstack details summary { cursor: pointer; padding: 6px 0;
                              color: var(--info); font-size: 13px; }

No standalone template (generated as needed, clear structure, can be inspired by the step section of plan.html).

Common principles

Risk labels must be judgments the agent actually provides, not "All files look fine"
Line-numbered diffs must be monospace——Only browser rendering gives the "diff" feel
Where to focus should always include "what I did NOT do"——to avoid the reviewer wasting time asking "why wasn't X added"
PR writing's file-by-file should follow reading order, not alphabetical order——tell the reviewer where to start