rich-html · does visual evidence earn its place?

Same decisions, two ways to show the evidence.

Each scenario below is rendered twice from identical content. Only the expandable evidence differs — Baseline describes it in prose; Improved keeps the prose and adds the supporting artifact under it (code, chart, diagram, layout sketch). Flip the control above to focus one arm, or read them side by side and judge.

Baselineprose evidence only — html-doc as it read before §4 Improvedprose + one supporting artifact — text is still the point

/decidecode forkform: code snippet + path-in

Where should retry/backoff for outbound HTTP live?

A real fork parked in a PR thread: centralize the logic, or add it per call-site. The choice turns on how requests actually flow through the code.

Baselineprose evidence

Retry/backoff for outbound HTTP — centralize it, or per call-site?

Centralize in the client wrapperrecOne place; covers every call at once.
Add it per call-siteFlexible per call, but repeated and easy to forget.

Context — the two locations

Every outbound request already passes through a single request() function in the client wrapper, and that wrapper already exposes an interceptor hook. Putting backoff there would cover all 37 call sites at once. The per-call-site option repeats the logic and risks call sites that forget to add it.

Improvedprose + code

Retry/backoff for outbound HTTP — centralize it, or per call-site?

Centralize in the client wrapperrecOne place; covers every call at once.
Add it per call-siteFlexible per call, but repeated and easy to forget.

Context — the two locations

Every outbound request already passes through a single request() function, which already exposes an interceptor hook — so backoff added here covers all 37 call sites.

// client.ts:42 — every outbound call funnels through here
async function request(opts) {
  // ← backoff hook goes here: wraps all 37 call sites
  const res = await withRetry(() => fetch(opts.url, opts), policy);
  return res;
}

Path in: apiFor(x).get() → request() — no call site touches fetch directly.

What to look for. Axes 1 & 3 — with the snippet and the one-line path, can you commit to “centralize” without opening the repo? In Baseline you have to trust the sentence “everything funnels through request().”

/decidelayout forkform: divs+CSS sketch

Dashboard header — single-row toolbar, or split title and actions?

The form most likely to drift toward a mockup. The sketch has to stay a schematic thumbnail you choose against — not a facsimile of the product.

Baselineprose evidence

Dashboard header layout — one row, or title over actions?

Single row: title + 3 actions inlineCompact on desktop; actions wrap awkwardly under 768px.
Two rows: title, then actionsrecTaller, but stable on small screens.

Context — the two layouts

Option A keeps the title and the three action buttons on one line — compact on wide screens, but the buttons wrap under the title awkwardly below 768px. Option B gives the title its own row with the actions beneath it: one row taller, but it holds its shape at every width.

Improvedprose + sketch

Dashboard header layout — one row, or title over actions?

Single row: title + 3 actions inlineCompact on desktop; actions wrap awkwardly under 768px.
Two rows: title, then actionsrecTaller, but stable on small screens.

Context — the two layouts

Schematic thumbnails, not a mock — enough to compare the shapes:

A · single row

B · two rows

What to look for. Axis 5 (drift) lives here. The sketch is grey blocks — it shows arrangement, not the product. If a form ever needs real colors, type, and states, that’s the signal it belongs in mockup, not decide.

/reporttrendform: chart (via dataviz)

Did PR merge throughput recover after the March dip?

A report finding that is a shape over time — the form a report reaches for most. The numbers are in the prose either way; the chart is what makes the recovery legible at a glance.

Baselineprose evidence

PR merge throughput dipped in March, then fully recovered by June.

Merged PRs fell from 21 in February to 9 in March during the incident freeze, then climbed back — 18 in April, 27 in May, 31 in June, above the pre-dip baseline.

Evidence — monthly merged PRs

Jan 24 · Feb 21 · Mar 9 · Apr 18 · May 27 · Jun 31 (source: gh pr list --state merged)

Improvedprose + chart

PR merge throughput dipped in March, then fully recovered by June.

Merged PRs fell from 21 in February to 9 in March during the incident freeze, then climbed back — above the pre-dip baseline by June.

Evidence — monthly merged PRs

Merged PRs per month · source gh pr list --state merged · single series, one hue (dataviz)

What to look for. Axis 1 (grasp). The V-shape — dip at March, peak at June — reads in one saccade from the chart; the same fact in the prose list makes you assemble it from six numbers.

/reportflowform: inline-SVG diagram

How did the guest checkout flow change?

A page A→B→C change. A diagram shows the inserted step in place; the prose has to spell out a before-and-after the reader holds in their head.

Baselineprose evidence

Guest checkout now inserts one optional-account step before shipping.

Previously the flow was Cart → Shipping → Payment. The new flow adds a Details step — where a guest can skip account creation — between Cart and Shipping, so the path is one screen longer for everyone.

Evidence — the route change

Old: /cart → /shipping → /pay. New: /cart → /details → /shipping → /pay (see PR #412).

Improvedprose + diagram

Guest checkout now inserts one optional-account step before shipping.

A new Details step — where a guest can skip account creation — now sits between Cart and Shipping, one screen longer for everyone.

Evidence — the route change

Guest checkout route · the dashed node is inserted · source PR #412

What to look for. Axis 2 (decide/conclude in place). The inserted node is visually obvious in its position; the prose makes you diff two /cart → … → /pay strings to find the one that’s different.

Scoring rubric

Five axes, Baseline vs Improved. Axes 1–3 are your call — they’re reader experience, which is exactly what this page exists to let you feel. Axes 4–5 I can read directly, filled below.

Axis	Baseline	Improved
1 · Time to grasp the fork	your call — read the prose arm	your call — read the artifact arm
2 · Decide/conclude without leaving the page	your call	your call
3 · Confidence in the pick	your call	your call
4 · Build + file-size cost	Lowest — prose only.	Modestly higher: inline SVG/code adds roughly 1–4 KB per artifact and a little authoring effort (the chart borrows the dataviz palette). Still one self-contained file, no network — the format contract holds.
5 · Drift toward mockup	None — nothing visual to over-build.	Low for code / chart / flow. The one to watch is the layout sketch (scenario 2); kept schematic here, it stays a thumbnail. If it ever wants real color/type/state, that’s the line into `mockup`.