report-with-html
Create a reader-facing HTML artifact whose information architecture follows the
reader's question—not the author's implementation checklist.
Trigger boundary
Use this skill when the requested artifact is itself a visual HTML report or
interactive information tool. Typical outputs include:
- a system, architecture, journey, causal, decision, comparison, or gap view;
- a client-facing data report or one-pager;
- a data/archive browser or review workbench;
- an explicitly requested HTML/web presentation.
Do not trigger it for a normal status reply, generic review, code diff, issue list,
or Markdown document. Those tasks may be reported in chat unless the user explicitly
asks to turn the result into a visual HTML artifact.
For restoring or hosting an existing HTML page without changing its content,
take Existing HTML restoration
and stop after its delivery checks. This transport-only route does not enter the
new-report design, masked-render or reader-review workflow below. If the request
also changes the report's conclusions, layout or interactions, use the applicable
authoring/maintenance workflow for those changes.
For a local report that needs HTTP preview, use
references/local-http-preview.md and its bundled scripts/preview_report.py.
Serve only the reviewed explicit file
snapshot; verify its HTTP readiness and rendered content/action in the permitted
browser.
For a course/archive browser, use the hierarchical reader
and its reusable builder/PDF adapter. Preserve current source navigation, historical
nodes and stable material IDs; verify lesson resources, actual PDF pages and media
play/seek through the existing source-owned asset server.
The default delivery is the verified HTML opened in a browser. A PNG is a QA artifact
and is delivered only when the user asks for an image. If the user needs editable
PowerPoint, finish and verify the HTML first, then use deck-creator (Route C).
SSOT map
Visualization judgment lives in another skill — load it before designing any chart or
geometry. data-visualization-discipline:data-visualization-discipline owns which form
fits the content, which chart type and summary statistic to use, whether segments may be
aggregated, how many categorical colors are allowed, cross-view color identity, table
discipline, the antipattern list, and the pre-delivery self-check gate. This skill does not
restate those rules; a second copy would drift. This skill owns the report page itself:
register calibration, the component shelf, the approved corpus, page order, the decision-card
contract, interaction contracts, and browser verification.
- Reader-facing principles, content boundary, decision-card contract, accessibility:
references/design-principles.md
- Layout density (铺满画布 / 消灭空洞), page order as narrative rhythm, the HTML table
micro-spec, and form → component implementation:
references/visualization-patterns.md.
Not conditional on having already chosen a form — most of it applies to every page
regardless of what you draw.
- Approved corpus and register calibration:
references/approved-examples.md
- Reusable interactions and their keyboard contracts:
references/interaction-components.md
- Parameter exploration, selected-record follow-up and recoverable workbench state:
references/interactive-analysis.md. Load before authoring those interactions;
keep static reports on the ordinary path.
- Numbered hover/focus source previews and original-content adapters:
references/citation-source-preview.md (candidate/pilot; load when citations use previews).
- Photos, screenshots and explanatory diagrams:
references/visual-evidence.md.
Load before authoring when objects, physical choices, visual defects or relationships
need to be seen; do not wait until images have already been selected.
- Long-lived/generated-page maintenance:
references/long-lived-report-maintenance.md
- Version-comparison reading order, paired evidence and full-text inspection:
references/version-comparison-reading.md. Load when the page explains what
changed between editions; keep source interpretation separate from presentation.
- Fresh-context review payload:
references/independent-review-prompt.md
- Warm-paper starter implementation:
assets/report-template.html
Read these before authoring — the principles, the patterns file, the closest
approved example, and data-visualization-discipline. The rest are activated by what the
artifact actually contains.
Do not let "read only what's activated" decide the required sources above. That filter operates over needs
you already know you have, so it is structurally unable to surface a step you don't know
exists — and it hands the skip a legitimate-sounding rationale, which is worse than forgetting.
These are the sources that tell you which steps exist.
Product contract
Reader and evidence first
Write down the audience, the decision or understanding the page must enable, and the
authoritative sources before choosing components. Retrieve current facts during this
session. Every number needs a unit, date/window, and traceable source; unknown values
stay unknown.
Screen copy may contain a factual takeaway when the same page visibly supports it
with data, mechanism, or primary evidence. Remove unsupported value judgments,
slogans, maxims, superlatives, and unproven causal claims. A grep pattern such as
不是.*是 only surfaces candidates; its presence alone is never a failure. Judge each
candidate with the test in design-principles.md §3 — delete the sentence, and ask
whether the reader loses a fact they could have checked on this page, or only an opinion.
The first stays, the second goes.
Use complete, audience-readable language. Internal codes, private shorthand, naked
algorithm scores, and unexplained abbreviations do not belong on the page.
Let the question choose the skeleton
- “How does it work?” → journey, architecture, or mechanism.
- “What should we decide?” → options, trade-offs, decisive unknowns, recommendation.
- “Why did it happen?” → timestamped causal chain plus falsifying evidence.
- “Which is better?” → entities × criteria on a common baseline.
- “Let me inspect this collection.” → list/detail, search/filter, state, provenance,
deep links, and review-output return path.
Implementation state is a badge on that skeleton, not the skeleton itself. A missing
dependency, unverified result, or unknown must remain visible.
For technical selection or purchase comparisons, use the concrete-plan reading order
in references/visualization-patterns.md before arranging sections. Distinguish choosing
what to investigate next from authorizing a purchase or deployment.
Geometry and real evidence
Use position and length for important quantitative comparisons. Color carries category
or state, not a second independent measure. A geometry needs an explicit encoding key
and a data-supported readout.
Do not redraw the same entity set in multiple decorative forms. Each section must
answer a different sub-question. For UI or visual-product review, real screenshots are
the primary evidence: crop the exact defect with enough surrounding context and keep
before/after crops identical.
Use an installed mature charting capability or the current project's declared chart
stack for statistical charts. If neither exists, research and select a maintained
library before implementing; do not hand-build a chart engine.
Interaction and accessibility
For calculators or workbenches that continue from the reader's parameters or
selection, load references/interactive-analysis.md before implementing controls,
state recovery or the return to the conversation. Keep context preparation,
state saving and an explicit message send distinct; use a manual handoff in a
standalone browser.
Evidence comes to the reader; the reader does not travel to the evidence. When the
page cites a clause, a screenshot, or a source passage, embed it at the point of citation
— an in-place overlay or drawer that returns the reader to where they were. An anchor
that throws the reader elsewhere on the page and expects them to navigate back is
prohibited, not merely discouraged; design-principles.md §13 holds the rule and the
user's own words for it. Hash anchors remain correct for nav and for external deep links:
what is banned is being forced to leave mid-read.
Copy approved interactions from assets/components/ instead of rebuilding them.
Behavior is part of the component contract; register-specific styling may change.
Copy each component through its complete contract:
- Read the component file's own header contract — it states prerequisites the registry
table does not repeat (required CSS tokens, required DOM structure, which element
types it scans).
citation-drawer, for instance, only linkifies inside <section>
elements and needs a generator-produced #s9.
- Make those prerequisites true in your page.
- Click the component's primary interaction in a real browser before delivery. A
component can be present, id-unique, tag-balanced and completely inert — every static
check passes while the feature does nothing. Only the click distinguishes those two
worlds.
Every interaction must work without a pointer:
- use native buttons, links, and dialogs when available;
- provide a visible close control and Escape handling for modal surfaces;
- keep focus inside an open modal and restore it to the invoker on close;
- expose names, states, and relationships with semantic HTML and ARIA;
- preserve visible focus, logical tab order, and usable narrow-screen geometry.
Workflow
Choose verification from the actual changed axes and still-valid evidence, not from the
number of edits. For the first delivery of a complex report, retain both independent
reader comprehension (step 9) and load-bearing source checks (step 10). They need not
always be two agents: one independent agent may first return and freeze a genuinely
page-only blind read, using the canonical prompt verbatim, and only then receive the
sources and acceptance packet. Never expose author findings, conclusions, or proposed
fixes to that agent before its blind read is frozen.
For a later delta to an accepted report, invalidate only evidence covering changed
claims, visual encoding, layout, interactions, or decision structure. When input,
configuration, criterion, and relevant state are unchanged and no new failure signal
exists, keep unrelated evidence valid. Re-render and recheck affected axes after chart,
layout, or interaction changes. Repository-required checks remain required. Stop when
the named result is decided; do not add a reviewer merely because a small fix landed.
Define success. Record audience, question, source set, required evidence,
delivery form, and what would make the artifact fail. The gate template (step 5) also
always carries a 读者已知清单 slot — fill it when the declared audience is narrower than
"any reader" (an internal, already-informed reader rather than a stranger): the specific
terms, scripts, or systems that audience is assumed to already know, in checkable
backtick-quoted form. When the audience genuinely is a stranger, write
不适用: <why> — the slot still has to be filled, just with that answer. Write this before
step 9's first review, not after one returns findings — see references/audience-triage.md
for why the ordering is load-bearing and how step 9 uses this list.
Resolve the actual reader and intended use from the original request, later corrections,
and the current project contract. Distinguish a publication-ready draft from an actual
external publication. Set evidence precision for that use: for private investigation,
retain traceable original identifiers, paths, and logs rather than silently substituting
a public, redacted edition. Follow the authorized project's existing delivery directory
or document library; a scratch directory is a working location. If no destination is
established, choose a reversible local default and state it. Ask only for missing inputs
that materially affect the result and cannot reasonably be defaulted. For an investigation,
record complete readability and proof of the core causal claim as separate acceptance
results. A readable report does not close the investigation while necessary, authorized
actions can still advance that claim; unavailable historical evidence remains unknown.
Calibrate. Read the mandatory sources — design-principles.md,
references/visualization-patterns.md, the closest entry in approved-examples.md, and
data-visualization-discipline — then any component reference the artifact activates.
Use the nearest approved register; do not copy a skin blindly.
Plan visual evidence and 造量纲 — before a line of HTML. First follow
references/visual-evidence.md for sections about concrete objects, physical choices,
visual defects or relationships. Put representative images at the relevant options
and explain connections with diagrams; identify unavailable evidence explicitly.
Record the selected visuals in the existing page intent, not a second inventory.
Section by section, name what in the content is
ordered / has magnitude / has direction / has a counterpart, and write that quantity
down. Each geometry then carries it in the markup:
<div data-geometry="退款家数刻度轴"
data-derived-from="退款家数(0–30 家线性,共同基线;位置=家数÷30)"> … </div>
No supported quantity or relationship means no invented geometry. Keep that
content as prose; a verified photo or screenshot can still show the object or evidence.
Wrapping a sentence in a coloured box does not make it a diagram.
A number and the coordinate that encodes it come out of the same script. As soon as
any geometry is positioned by a computed value — a bar length, a tick at left:30.80%,
an axis label, a line's endpoints — write a small no-dependency script that prints both
the finding and the coordinates, paste from its output, and ship the script next to the
page. Computing the value in prose and then hand-writing the SVG attribute is a two-copy
fact with no grep that can catch the drift: it is how the same quantity ends up rounded
two different ways in two sections, and how an axis label lands at the position of a
smaller number — a lie factor authored by the very page arguing against lie factors.
Shipping the script also makes the drawing auditable: a reader re-runs it and diffs.
Step 5's gate asks for that script's path and stats the file, so this rule has a machine
consumer rather than being one more thing only you referee.
Author. If a calling Skill supplies a user-approved local report form that still
fits this report's output contract, use that form as the starting point. Otherwise
start from assets/report-template.html or an approved example. The calling Skill
owns template approval and storage; this Skill owns report generation and visual QA.
Keep customer facts and conclusions tied to current evidence, and do not copy the
caller's template into this Skill's update-owned assets/. Before updating an accepted
report's facts or content, follow the incremental maintenance recipe.
Use actual shelf components for new or changed interactions; retain the approved
embedded implementation during a data-only update. If the page embeds mutable source documents, follow the long-lived-report
reference and keep generated and authored regions separate.
Run the delivery gate — it produces the artifacts the judgment steps otherwise skip.
uv run <skill-dir>/scripts/delivery_gate.py init page.html [--height 9600]
# → renders page.png AND page--masked.png (all text transparent — the squint test,
# headless; see the script header for the technique's provenance)
# → scans for ≥120 CSS px whitespace voids (visualization-patterns.md 版面填充纪律)
# → writes page.html.gate.md: the delivery gates + the stage-1 questions
# (`STAGE1` in delivery_gate.py owns the exact list), every slot empty
# Read the masked PNG segment by segment, fill every slot, then:
uv run <skill-dir>/scripts/delivery_gate.py check page.html # exit 1 until it passes
check fails on: a missing or stale masked render (so 遮字自测 cannot be claimed without
the evidence), a percentage-driven visual with no data-geometry/data-derived-from (so
造量纲 cannot be skipped — pure-layout boxes opt out visibly with data-layout), any
unfilled slot, and a gate file older than the page (so "filled the checklist, then kept
editing" cannot pass). It asserts these steps happened; it says nothing about whether
the conclusions are right — that is still steps 9 and 10.
Render a fresh artifact. Step 5 already produced page.png at the height you passed
it; re-render here only when you changed the page since, and pass the same height —
render_report.sh overwrites in place, so a shorter H silently replaces a good render with
a truncated one.
<skill-dir>/scripts/render_report.sh page.html page.png 1300 2400 # H is an example, not a default
<skill-dir> is this skill's own directory — its absolute path is given to you when
the skill loads. Bare relative paths like report-with-html/scripts/… only resolve
from one particular parent directory and fail with exit 127 anywhere else.
The renderer fails without a new valid PNG and never treats an existing output as
success. Set CHROME_BIN to an explicit managed Chrome/Chromium executable in CI
or a shared-browser environment; an invalid override is a hard failure.
Then split it and read every segment — a tall PNG exceeds what one Read can resolve:
uv run <skill-dir>/scripts/crop_segments.py page.png --segments 5
That step is also where truncation is caught. Chrome screenshots exactly the
--window-size you passed and never grows to fit, while the renderer's PNG check only
proves the bytes are a valid image — so a page taller than your H loses its tail
silently, and §6 of design-principles.md puts the strongest conclusion last. The
splitter warns when content runs to the final canvas row, which means the canvas cut
through the page rather than the page ending inside it. It is checked here rather than
in the renderer because the only non-mutating way to measure page height is a second
--dump-dom call, and that hangs on some pages — a gate that can never measure is a
gate that always skips.
That warning has one false positive, and its obvious remedy does not terminate under
it — so read the warning's own two branches before you re-render. If the page sizes
anything in vh (a scrolling panel at max-height:78vh is the common case), headless
1vh is H/100, so raising H grows that element too and content stays pinned to the
canvas bottom at every H. Discriminate once by rendering at a clearly different H and
comparing the reported content bottom: unchanged means it was real truncation and is now
fixed; still ≈ the new canvas height means it is the vh loop. Do not keep doubling H —
an operator who sees the same warning at 3000 and at 40000 learns to ignore it, and a
gate trained into noise no longer catches the real truncation it exists for.
Also test the narrow-screen layout with real device emulation and measure overflow.
Device emulation is not optional phrasing: headless Chrome clamps --window-size to a
~500 CSS px minimum width (measured 2026-09-17: asking 390 yields innerWidth=500;
--force-device-scale-factor does not shrink the CSS viewport either). For 390-class
phone widths use Playwright/CDP Emulation.setDeviceMetricsOverride (or Ego) — never
report a --window-size=390 run as a phone-width test.
Measuring painted bar spans for the proportion gate: anchor on the container (find the
track box first, then measure dark pixels inside it), never cluster content pixels
globally — edge antialiasing creates phantom clusters and a long bar hides its own track
row (two real failures from 2026-09-17).
Exercise the journey. In a real browser, follow the reader's route—not merely
a click list. Test understanding order, the obvious next action, keyboard access,
modal focus, deep links, filters, and error/empty states. Use
frontend-visual-qa for micro, macro, and intent review. Every shelf component you
embedded gets its primary interaction clicked here, and you write down what you
observed — "the drawer opened and highlighted clause 7" is evidence; "the component
is present" is not. Check that actual images load, important details are readable,
captions remain next to their visuals, and the delivered local file has no missing assets.
Reconcile and verify.
For a merge or a current-state update, apply the semantic acceptance contract in
references/long-lived-report-maintenance.md §6.1. Keep the information-point
mapping with the gate evidence; a source-link index is not the requested synthesis.
For a rewrite or merge, run:
uv run --python 3.12 python <skill-dir>/scripts/reconcile_content_diff.py old.html new.html
It opens both pages in Chrome and compares their initial, computed reader-visible
text. This does not traverse tabs/accordions or other interaction-created states;
cover those states in the Journey/browser harness.
For generated long-lived pages, run the page generator and then its --check
mode. Missing/duplicate anchors or stale output are failures.
Search for stale facts, shorthand, unsupported claims, broken file paths, and
duplicated version/status values.
Independent reader review — and leave a file saying it happened. The reviewer
must start with no inherited conversation or author reasoning: in Codex use
fork_turns: "none"; in Claude Code start a separate non-fork general-purpose
agent and put all required reader context in its prompt. Give that reviewer the HTML plus its
rendered screenshots — and nothing else (the table below says "the page and nothing else";
screenshots are the page, a text-only reviewer answers the visual questions by reading
source, which is indistinguishable in the write-up from having looked), using
references/independent-review-prompt.md verbatim. Reader comprehension failures
are defects — with one exception, 读者已知清单 below, that a page not declaring a
narrow audience never gets to claim. Treat proposed implementation changes as
hypotheses and reproduce them before changing the artifact.
Confirm the reviewer can actually open a browser before you send it the page — several
of the review questions are about focus, Escape and keyboard order, and a text-only
reviewer will answer them by reading the source. You cannot introspect a subagent's
capabilities before spawning it, so make it the reviewer's own first action: tell it to
attempt the browser step and report "browser unavailable — items 7 and 8 answered from source"
in its output if it cannot. An unmarked source-read answer is the failure; a marked one
is a known gap you can cover another way. That answer is indistinguishable in
the write-up from one produced by clicking, and it lands in exactly the blind spot this
skill warns about: every static check passes while the feature does nothing.
Write the outcome to a file next to the page (or in your review archive): how the
reviewer was spawned (agent type, and that it was not a fork), the prompt you gave,
each finding with its disposition and reason, and what could not be checked. Record the
spawn details because a fork's write-up reads identically to an independent one — the
only thing that distinguishes them is a fact about how it was launched, and if that is
never written down, the independence requirement above is unverifiable by anyone
including you. The file itself is the point: a review that leaves nothing behind is
indistinguishable from a review you meant to run and didn't, and that is the failure
mode this step actually has. It is not that authors disagree with the step; it is
that under delivery pressure the step is the cheapest thing to silently drop.
Triage every "I don't understand this" finding against 读者已知清单 before it counts —
provisionally; step 10 independently re-derives it, this isn't a self-check. The
reviewer's zero-context persona is deliberate and does not change — but a term that is on
the list committed in step 1 is a phantom problem (Sauro, MeasuringU): the reviewer
correctly has no way to know it, and the declared audience isn't actually confused by it.
Quote the reviewer's finding verbatim next to the list entry it's disposed against —
"reduces to a known term" is an interpretive claim, not a file-exists check, and the quote
is what lets someone other than you judge whether the reduction was honest. Log the
disposition as audience-declared-known with that quote and reason; it does not count
toward the same-axis-recurrence test below. A flagged term that is not on the list either
stands as a real finding, unchanged from today, or gets added now — in which case say so
directly in the gate file next to the entry (补记于 cycle N 审阅之后) rather than blending
it into the original list silently. Do not backdate it: init --force's preserved
"上一轮的答案" appendix already carries the list as it stood before this cycle, so a
silently-blended addition is trivially caught by diffing the current list against that
appendix — say it plainly instead of relying on someone doing that diff. Full mechanism and
the grounding for why this pass is provisional rather than final are in
references/audience-triage.md.
Deciding whether to run it again is an observation about invalidated evidence, not an
edit count. Compare the delta with the claims and reader decisions the recorded review
covered. A number, term, or label change triggers a fresh page-only review only when it
invalidates the previous reader's interpretation of an affected claim, visual encoding,
layout, interaction, or decision structure; not every number or term change does. Reuse
unrelated review evidence when its input, configuration, criterion, and relevant state
are unchanged and no new failure signal exists. A local NAS-name correction, a
normalized-copy hash label, or an actionable gap-card correction requires readback of
every affected projection and its meaning, not another unchanged full QA pass. Typo and
punctuation fixes need only the affected readback. Chart, layout, or interaction changes
require a fresh render and rechecks of the affected axes. Stop once the named finding is
resolved; do not dispatch a new reviewer just because its small fix landed.
A required re-review has no ceiling of its own — pair it with a budget, or "any
invalidating edit needs review" mints an unbounded stream of fresh rounds. A local fix
whose affected readback resolves the named finding without invalidating the blind read
does not start another cycle. When re-review is required, a converging review and a
runaway one are indistinguishable from inside a single round — the failure has been
observed at both small scale (three full rounds to close one low-stakes correction) and
large (21 rounds on a real decision document, stopped only because a human asked why).
This is the Loop Contract from
claude-code-hooks's SKILL.md rule 7 — "If the hook demands remediation, prove the
loop terminates"
(daymade-claude-code/claude-code-hooks/SKILL.md (daymade/claude-code-skills),
read there for the general framework and its worked failure cases) — instantiated for
this step instead of a hook:
LOOP KEY: this delivery's lineage (the HTML frozen at round 1 plus every descendant
edit) + one failure axis: can a fresh, uninformed reader use this page?
FIRE T: after audience triage (above), a review still answers review-prompt item 9
"no" — or surfaces any finding that amounts to the same thing (the reader
could not actually make the decision this page exists to produce) — on that
same axis, using only findings that survived triage
REMEDIATION R: reproduce the finding, apply one bounded fix, and read back every affected
projection and its meaning; re-run the blind review once only if that
delta invalidates its axis
VARIANT V: 2 - completed review cycles for this lineage
BUDGET: 2 cycles total — the initial review plus one narrowly scoped re-review.
A third reviewer on this lineage is never automatic.
SUCCESS EXIT: the affected readback resolves the named finding without invalidating
existing blind-read evidence; otherwise the single re-review answers item 9
"yes" on that same axis, with nothing else reopening it
AUDIENCE-MISMATCH EXIT: EVERY SINGLE post-triage reason behind a cycle's "no" disposes as
audience-declared-known — ship, log the disposition table, do not report this
to the user as blocked. "Every" means every: a "no" with two reasons, one
audience-related and one a genuine unrelated defect (a chart missing a unit, a
broken cross-reference), is not this exit — the unrelated reason alone routes
through ordinary REMEDIATION/CAPPED EXIT, same as if it had appeared by itself.
This can fire after cycle 1 alone: if nothing survived triage, there is no
finding for REMEDIATION to reproduce and fix, so a mandatory cycle 2 would just
re-review an unchanged page for a second phantom verdict.
(see `references/audience-triage.md`)
CAPPED EXIT: at least one post-triage finding is real and recurring across two cycles —
stop, report the remaining findings as a backlog, do not ship silently, and do
not dispatch a third reviewer on your own authority
This skill's own reviewer output has no severity vocabulary to key off — the review
prompt (references/independent-review-prompt.md) returns answered questions, not
BLOCKER/MAJOR-rated findings, and step 10's acceptance vocabulary is PASS / FAIL /
CANNOT-CHECK — so FIRE T and SUCCESS EXIT above are keyed to review-prompt item 9's own
"最后一问" answer (can the reader act on this page with no other explanation?) rather
than to rule 7's example severity labels, which describe a different kind of review and
don't otherwise appear anywhere in this skill.
A same-axis recurrence and a new, unrelated finding get different treatment on
cycle 2 — conflating them is what turns a bounded loop into an expanding one. Apply
the audience triage above to each cycle's findings first; everything below is about
what survives it. If cycle 1's findings dispose entirely as audience-declared-known,
take the AUDIENCE-MISMATCH EXIT right there — there is nothing left for cycle 2 to
re-review.
- Cycle 2 reproduces a comprehension failure on the same axis cycle 1 already
named (the reader still can't use the page, even if the specific wording changed) →
that is the CAPPED EXIT above only if the finding survived triage. If both
cycles' reasons dispose entirely as audience-declared-known, that is the
AUDIENCE-MISMATCH EXIT instead — ship, don't report blocked. When a real,
post-triage finding does recur: stop. Report
blocked. Do not reason "but this
finding is real" into a third dispatch — realness was never the missing check; a new
user-authorized task with its own predeclared budget is what's missing, and only the
user can open one.
- Cycle 2 surfaces something genuinely new and unrelated (cycle 1 was about a
decision card's clarity; cycle 2 incidentally flags an unrelated color problem) →
record it as a separate backlog item for a separate task. It does not consume this
lineage's budget and, by itself, is not grounds for a cycle 3 on this lineage — ship
what converged, and open the new item as its own review with its own budget if the
user wants it pursued now.
Stop after the named result is decided. Once steps 9/10 have returned the verdict for
the current delta, do not reopen them merely because a small accepted fix landed. A later
maintenance delta selects its own bounded evidence under §6.3; only invalidated axes are
rechecked. A third reviewer on the same unresolved comprehension lineage is still never
automatic.
Independent acceptance. Either hand the acceptance checklist below, the page and its
sources, and the original request, later corrections, output contract and required
acceptance criteria to a second fresh-context agent, or use the step 9 independent agent
after its page-only blind read has been returned and frozen. The latter is the sequential
route defined at Workflow entry, not permission to leak sources, author findings, or
proposed fixes before that freeze. Keep the two phases separate because they answer
different questions (see the table under that list). The acceptance phase returns a verdict
and evidence per item. Its FAILs are findings you reproduce and fix, exactly like step 9's;
its PASSes are the only thing that closes an item.
Finalize after review. Apply accepted fixes, then select only checks invalidated by
the actual changed axes. Re-render and recheck affected visual, layout, or interaction axes
after chart, layout, or interaction changes; rerun only affected journeys and masked/gate
artifacts. For a local text-only delta, read back every affected projection and its meaning.
If a particular gate or check is inapplicable to that delta, record
inapplicable: <reason> and the relevant readback; never describe a stale gate as green.
If the page contract or repository still requires a check, run it. For an invalidated
delivery gate, re-run init --force, read the new masked render, carry forward only answers
confirmed against it, then run check again. Reuse unrelated evidence only while its
inputs, configuration, criteria, and relevant state remain unchanged and no new failure
signal exists. Only then open the final HTML for the user. Do not open a pre-review draft
as the delivered artifact.
Where a new lesson goes — answer in this order before writing one into this skill.
*First: was the failure "I forgot to do it" or "I did it and could not see it was
wrong"?* The first belongs in the workflow above; a reminder solves it. The second has to
become a question somebody else asks, because the author did not skip it — they looked
straight at it and judged it fine. Colour, terminology, whether a chart supports its own
caption, whether a decision card is missing an option: all of the second kind. Putting
those on a list the author answers is exactly how a rule ends up written down and still
violated — which is what happened to every rule this skill had to relearn the hard way.
Then, if it is somebody else's question: can it be answered from the page alone?
Yes → the reader's prompt (references/independent-review-prompt.md). No → the acceptance
list below. That second question is what keeps the two lists from growing copies of each
other; the table below states the same boundary from the other side.
Delivery acceptance — an independent agent runs this list, not you
Reader review and acceptance close a delivery, and they do not overlap: every check lives in
exactly one of them, so there is nothing for them to drift apart on.
|
step 9 · reader review |
step 10 · acceptance |
| gets |
the page and nothing else (screenshots count as the page) |
the page plus the original request and corrections, output contract and required acceptance, your sources, commands, review file, and the gate artifacts |
| asks |
can you read it? can you decide from it? |
does it deliver the requested result, and does what is off the page agree with what is on it? |
| its questions live in |
references/independent-review-prompt.md — all of them, used verbatim |
the items below |
| authority |
everything visible on the page |
original task requirements, provenance and process |
The split rule, so a future addition lands in one place instead of both: does answering
it require something outside the page? No → it is a reader question; add it to the
review prompt. Yes → it belongs here. Colour, wording, whether a chart supports its own
caption, whether a decision card is missing an option, whether the headings form an
argument — all visible on the page, all the reader's. The checks below need what the
reader does not have.
Hand this list, the page and its gate artifacts (page.html.gate.md, page--masked.png),
the original request and later corrections with their source coordinates, the existing output
contract and required acceptance criteria, the sources behind load-bearing facts, the commands
you ran, and the step 9 review file to the acceptance agent selected in step 10. You may walk it yourself first — it catches the
obvious misses cheaply — but you do not get to declare the items passed.
Why it cannot be a self-check, stated plainly because the urge to skip it peaks exactly
when delivery is close: an earlier version of this list asked the author to "be able to
point to" each item, which they could always sincerely claim. Rewriting it to demand pasted
evidence fixed half the problem — the evidence now exists — and left the other half, because
the author still ruled on whether their own evidence sufficed. The failures behind these
items were all that shape: a chart its author found perfectly clear, a colour scheme they
had considered and approved, a recommendation whose missing downside they never noticed.
None was a forgotten step. Reminders do not reach errors like these; a second pair of eyes
does.
Ask for: item number, PASS / FAIL / CANNOT-CHECK, and the specific evidence — a quoted
line, a count, a command's output. An item that cannot be checked is reported as such,
never as a pass.
- Requested result — the existing acceptance agent first maps each required reader
question or output to its answer and evidence in the delivered page, quoting the requirement
and the page location. Missing answers or a sample/prototype substituted for a required
report are FAILs even when interactions, rendering and gates pass. A sample-only request is
judged against that scope; do not require a full report it never requested. Missing original
requirements are CANNOT-CHECK; do not infer them from the author's narrower contract.
This is semantic acceptance, not something the delivery-gate script establishes.
- Provenance — every load-bearing fact traces to a source outside the page, with an
as-of date: not only numbers, but quoted clauses, claims about what someone agreed to,
statements about a dependency's status. The reader can check a page against itself;
only this pass can check it against the world. Anything untraceable is removed from the
page or visibly marked unknown.
For sourced images, match the actual file to its original publisher and ex
…(truncated)
1---2name: report-with-html3description: >-4 Produces the reader-facing HTML artifact — report, dashboard, architecture view, data browser, or5 review workbench — evidence-backed, browser-verified. Use when the deliverable IS a visual HTML6 report, or the user asks for an HTML/web presentation. Load data-visualization-discipline for7 chart judgment. Not for chat status or Markdown prose unless asked to become a report; not for8 PowerPoint (deck-creator Route C).9metadata:10 source: https://skillmd.com/skills/daymade/report-with-html11---1213# report-with-html1415Create a reader-facing HTML artifact whose information architecture follows the16reader's question—not the author's implementation checklist.1718## Trigger boundary1920Use this skill when the requested artifact is itself a visual HTML report or21interactive information tool. Typical outputs include:2223- a system, architecture, journey, causal, decision, comparison, or gap view;24- a client-facing data report or one-pager;25- a data/archive browser or review workbench;26- an explicitly requested HTML/web presentation.2728Do not trigger it for a normal status reply, generic review, code diff, issue list,29or Markdown document. Those tasks may be reported in chat unless the user explicitly30asks to turn the result into a visual HTML artifact.3132For restoring or hosting an existing HTML page without changing its content,33take [Existing HTML restoration](references/local-http-preview.md#existing-html-restoration)34and stop after its delivery checks. This transport-only route does not enter the35new-report design, masked-render or reader-review workflow below. If the request36also changes the report's conclusions, layout or interactions, use the applicable37authoring/maintenance workflow for those changes.3839For a local report that needs HTTP preview, use40`references/local-http-preview.md` and its bundled `scripts/preview_report.py`.41Serve only the reviewed explicit file42snapshot; verify its HTTP readiness and rendered content/action in the permitted43browser.4445For a course/archive browser, use the [hierarchical reader](references/archive-reader.md)46and its reusable builder/PDF adapter. Preserve current source navigation, historical47nodes and stable material IDs; verify lesson resources, actual PDF pages and media48play/seek through the existing source-owned asset server.4950The default delivery is the verified HTML opened in a browser. A PNG is a QA artifact51and is delivered only when the user asks for an image. If the user needs editable52PowerPoint, finish and verify the HTML first, then use `deck-creator` (Route C).5354## SSOT map5556**Visualization judgment lives in another skill — load it before designing any chart or57geometry.** `data-visualization-discipline:data-visualization-discipline` owns which form58fits the content, which chart type and summary statistic to use, whether segments may be59aggregated, how many categorical colors are allowed, cross-view color identity, table60discipline, the antipattern list, and the pre-delivery self-check gate. This skill does not61restate those rules; a second copy would drift. This skill owns the report page itself:62register calibration, the component shelf, the approved corpus, page order, the decision-card63contract, interaction contracts, and browser verification.6465- Reader-facing principles, content boundary, decision-card contract, accessibility:66 `references/design-principles.md`67- **Layout density (铺满画布 / 消灭空洞), page order as narrative rhythm, the HTML table68 micro-spec, and form → component implementation:** `references/visualization-patterns.md`.69 **Not conditional on having already chosen a form** — most of it applies to every page70 regardless of what you draw.71- Approved corpus and register calibration:72 `references/approved-examples.md`73- Reusable interactions and their keyboard contracts:74 `references/interaction-components.md`75- Parameter exploration, selected-record follow-up and recoverable workbench state:76 `references/interactive-analysis.md`. Load before authoring those interactions;77 keep static reports on the ordinary path.78- Numbered hover/focus source previews and original-content adapters:79 `references/citation-source-preview.md` (candidate/pilot; load when citations use previews).80- Photos, screenshots and explanatory diagrams: `references/visual-evidence.md`.81 Load before authoring when objects, physical choices, visual defects or relationships82 need to be seen; do not wait until images have already been selected.83- Long-lived/generated-page maintenance:84 `references/long-lived-report-maintenance.md`85- Version-comparison reading order, paired evidence and full-text inspection:86 `references/version-comparison-reading.md`. Load when the page explains what87 changed between editions; keep source interpretation separate from presentation.88- Fresh-context review payload:89 `references/independent-review-prompt.md`90- Warm-paper starter implementation:91 `assets/report-template.html`9293**Read these before authoring** — the principles, the patterns file, the closest94approved example, and `data-visualization-discipline`. The rest are activated by what the95artifact actually contains.9697Do not let "read only what's activated" decide the required sources above. That filter operates over needs98you already know you have, so it is structurally unable to surface *a step you don't know99exists* — and it hands the skip a legitimate-sounding rationale, which is worse than forgetting.100These are the sources that tell you which steps exist.101102## Product contract103104### Reader and evidence first105106Write down the audience, the decision or understanding the page must enable, and the107authoritative sources before choosing components. Retrieve current facts during this108session. Every number needs a unit, date/window, and traceable source; unknown values109stay unknown.110111Screen copy may contain a factual takeaway when the same page visibly supports it112with data, mechanism, or primary evidence. Remove unsupported value judgments,113slogans, maxims, superlatives, and unproven causal claims. A grep pattern such as114`不是.*是` only surfaces *candidates*; its presence alone is never a failure. Judge each115candidate with the test in `design-principles.md` §3 — delete the sentence, and ask116whether the reader loses a fact they could have checked on this page, or only an opinion.117The first stays, the second goes.118119Use complete, audience-readable language. Internal codes, private shorthand, naked120algorithm scores, and unexplained abbreviations do not belong on the page.121122### Let the question choose the skeleton123124- “How does it work?” → journey, architecture, or mechanism.125- “What should we decide?” → options, trade-offs, decisive unknowns, recommendation.126- “Why did it happen?” → timestamped causal chain plus falsifying evidence.127- “Which is better?” → entities × criteria on a common baseline.128- “Let me inspect this collection.” → list/detail, search/filter, state, provenance,129 deep links, and review-output return path.130131Implementation state is a badge on that skeleton, not the skeleton itself. A missing132dependency, unverified result, or unknown must remain visible.133134For technical selection or purchase comparisons, use the concrete-plan reading order135in `references/visualization-patterns.md` before arranging sections. Distinguish choosing136what to investigate next from authorizing a purchase or deployment.137138### Geometry and real evidence139140Use position and length for important quantitative comparisons. Color carries category141or state, not a second independent measure. A geometry needs an explicit encoding key142and a data-supported readout.143144Do not redraw the same entity set in multiple decorative forms. Each section must145answer a different sub-question. For UI or visual-product review, real screenshots are146the primary evidence: crop the exact defect with enough surrounding context and keep147before/after crops identical.148149Use an installed mature charting capability or the current project's declared chart150stack for statistical charts. If neither exists, research and select a maintained151library before implementing; do not hand-build a chart engine.152153### Interaction and accessibility154155For calculators or workbenches that continue from the reader's parameters or156selection, load `references/interactive-analysis.md` before implementing controls,157state recovery or the return to the conversation. Keep context preparation,158state saving and an explicit message send distinct; use a manual handoff in a159standalone browser.160161**Evidence comes to the reader; the reader does not travel to the evidence.** When the162page cites a clause, a screenshot, or a source passage, embed it at the point of citation163— an in-place overlay or drawer that returns the reader to where they were. An anchor164that throws the reader elsewhere on the page and expects them to navigate back is165prohibited, not merely discouraged; `design-principles.md` §13 holds the rule and the166user's own words for it. Hash anchors remain correct for nav and for external deep links:167what is banned is being forced to leave mid-read.168169Copy approved interactions from `assets/components/` instead of rebuilding them.170Behavior is part of the component contract; register-specific styling may change.171Copy each component through its complete contract:1721731. Read the component file's own header contract — it states prerequisites the registry174 table does not repeat (required CSS tokens, required DOM structure, which element175 types it scans). `citation-drawer`, for instance, only linkifies inside `<section>`176 elements and needs a generator-produced `#s9`.1772. Make those prerequisites true in your page.1783. **Click the component's primary interaction in a real browser before delivery.** A179 component can be present, id-unique, tag-balanced and completely inert — every static180 check passes while the feature does nothing. Only the click distinguishes those two181 worlds.182183Every interaction must work without a pointer:184185- use native buttons, links, and dialogs when available;186- provide a visible close control and Escape handling for modal surfaces;187- keep focus inside an open modal and restore it to the invoker on close;188- expose names, states, and relationships with semantic HTML and ARIA;189- preserve visible focus, logical tab order, and usable narrow-screen geometry.190191## Workflow192193Choose verification from the actual changed axes and still-valid evidence, not from the194number of edits. For the first delivery of a complex report, retain both independent195reader comprehension (step 9) and load-bearing source checks (step 10). They need not196always be two agents: one independent agent may first return and freeze a genuinely197page-only blind read, using the canonical prompt verbatim, and only then receive the198sources and acceptance packet. Never expose author findings, conclusions, or proposed199fixes to that agent before its blind read is frozen.200201For a later delta to an accepted report, invalidate only evidence covering changed202claims, visual encoding, layout, interactions, or decision structure. When input,203configuration, criterion, and relevant state are unchanged and no new failure signal204exists, keep unrelated evidence valid. Re-render and recheck affected axes after chart,205layout, or interaction changes. Repository-required checks remain required. Stop when206the named result is decided; do not add a reviewer merely because a small fix landed.2072081. **Define success.** Record audience, question, source set, required evidence,209 delivery form, and what would make the artifact fail. The gate template (step 5) also210 always carries a `读者已知清单` slot — fill it when the declared audience is narrower than211 "any reader" (an internal, already-informed reader rather than a stranger): the specific212 terms, scripts, or systems that audience is assumed to already know, in checkable213 backtick-quoted form. When the audience genuinely is a stranger, write214 `不适用: <why>` — the slot still has to be filled, just with that answer. Write this before215 step 9's first review, not after one returns findings — see `references/audience-triage.md`216 for why the ordering is load-bearing and how step 9 uses this list.217218 Resolve the actual reader and intended use from the original request, later corrections,219 and the current project contract. Distinguish a publication-ready draft from an actual220 external publication. Set evidence precision for that use: for private investigation,221 retain traceable original identifiers, paths, and logs rather than silently substituting222 a public, redacted edition. Follow the authorized project's existing delivery directory223 or document library; a scratch directory is a working location. If no destination is224 established, choose a reversible local default and state it. Ask only for missing inputs225 that materially affect the result and cannot reasonably be defaulted. For an investigation,226 record complete readability and proof of the core causal claim as separate acceptance227 results. A readable report does not close the investigation while necessary, authorized228 actions can still advance that claim; unavailable historical evidence remains unknown.2292. **Calibrate.** Read the mandatory sources — `design-principles.md`,230 `references/visualization-patterns.md`, the closest entry in `approved-examples.md`, and231 `data-visualization-discipline` — then any component reference the artifact activates.232 Use the nearest approved register; do not copy a skin blindly.2333. **Plan visual evidence and 造量纲 — before a line of HTML.** First follow234 `references/visual-evidence.md` for sections about concrete objects, physical choices,235 visual defects or relationships. Put representative images at the relevant options236 and explain connections with diagrams; identify unavailable evidence explicitly.237 Record the selected visuals in the existing page intent, not a second inventory.238 Section by section, name what in the content is239 **ordered / has magnitude / has direction / has a counterpart**, and write that quantity240 down. Each geometry then carries it in the markup:241242 ```html243 <div data-geometry="退款家数刻度轴"244 data-derived-from="退款家数(0–30 家线性,共同基线;位置=家数÷30)"> … </div>245 ```246247 **No supported quantity or relationship means no invented geometry.** Keep that248 content as prose; a verified photo or screenshot can still show the object or evidence.249 Wrapping a sentence in a coloured box does not make it a diagram.250251 **A number and the coordinate that encodes it come out of the same script.** As soon as252 any geometry is positioned by a computed value — a bar length, a tick at `left:30.80%`,253 an axis label, a line's endpoints — write a small no-dependency script that prints *both*254 the finding and the coordinates, paste from its output, and ship the script next to the255 page. Computing the value in prose and then hand-writing the SVG attribute is a two-copy256 fact with no `grep` that can catch the drift: it is how the same quantity ends up rounded257 two different ways in two sections, and how an axis label lands at the position of a258 smaller number — a lie factor authored by the very page arguing against lie factors.259 Shipping the script also makes the drawing auditable: a reader re-runs it and diffs.260 Step 5's gate asks for that script's path and stats the file, so this rule has a machine261 consumer rather than being one more thing only you referee.2624. **Author.** If a calling Skill supplies a user-approved local report form that still263 fits this report's output contract, use that form as the starting point. Otherwise264 start from `assets/report-template.html` or an approved example. The calling Skill265 owns template approval and storage; this Skill owns report generation and visual QA.266 Keep customer facts and conclusions tied to current evidence, and do not copy the267 caller's template into this Skill's update-owned `assets/`. Before updating an accepted268 report's facts or content, follow the [incremental maintenance recipe](references/long-lived-report-maintenance.md#63-已验收报告的有界增量更新).269 Use actual shelf components for new or changed interactions; retain the approved270 embedded implementation during a data-only update. If the page embeds mutable source documents, follow the long-lived-report271 reference and keep generated and authored regions separate.2725. **Run the delivery gate — it produces the artifacts the judgment steps otherwise skip.**273274 ```bash275 uv run <skill-dir>/scripts/delivery_gate.py init page.html [--height 9600]276 # → renders page.png AND page--masked.png (all text transparent — the squint test,277 # headless; see the script header for the technique's provenance)278 # → scans for ≥120 CSS px whitespace voids (visualization-patterns.md 版面填充纪律)279 # → writes page.html.gate.md: the delivery gates + the stage-1 questions280 # (`STAGE1` in delivery_gate.py owns the exact list), every slot empty281 # Read the masked PNG segment by segment, fill every slot, then:282 uv run <skill-dir>/scripts/delivery_gate.py check page.html # exit 1 until it passes283 ```284285 `check` fails on: a missing or stale masked render (so 遮字自测 cannot be claimed without286 the evidence), a percentage-driven visual with no `data-geometry`/`data-derived-from` (so287 造量纲 cannot be skipped — pure-layout boxes opt out **visibly** with `data-layout`), any288 unfilled slot, and a gate file older than the page (so "filled the checklist, then kept289 editing" cannot pass). It asserts these steps **happened**; it says nothing about whether290 the conclusions are right — that is still steps 9 and 10.2916. **Render a fresh artifact.** Step 5 already produced `page.png` at the height you passed292 it; re-render here only when you changed the page since, and **pass the same height** —293 `render_report.sh` overwrites in place, so a shorter H silently replaces a good render with294 a truncated one.295296 ```bash297 <skill-dir>/scripts/render_report.sh page.html page.png 1300 2400 # H is an example, not a default298 ```299300 `<skill-dir>` is this skill's own directory — its absolute path is given to you when301 the skill loads. Bare relative paths like `report-with-html/scripts/…` only resolve302 from one particular parent directory and fail with exit 127 anywhere else.303304 The renderer fails without a new valid PNG and never treats an existing output as305 success. Set `CHROME_BIN` to an explicit managed Chrome/Chromium executable in CI306 or a shared-browser environment; an invalid override is a hard failure.307308 Then split it and read every segment — a tall PNG exceeds what one Read can resolve:309310 ```bash311 uv run <skill-dir>/scripts/crop_segments.py page.png --segments 5312 ```313314 **That step is also where truncation is caught.** Chrome screenshots exactly the315 `--window-size` you passed and never grows to fit, while the renderer's PNG check only316 proves the bytes are a valid image — so a page taller than your H loses its tail317 silently, and §6 of `design-principles.md` puts the strongest conclusion last. The318 splitter warns when content runs to the final canvas row, which means the canvas cut319 through the page rather than the page ending inside it. It is checked here rather than320 in the renderer because the only non-mutating way to measure page height is a second321 `--dump-dom` call, and that hangs on some pages — a gate that can never measure is a322 gate that always skips.323324 **That warning has one false positive, and its obvious remedy does not terminate under325 it — so read the warning's own two branches before you re-render.** If the page sizes326 anything in `vh` (a scrolling panel at `max-height:78vh` is the common case), headless327 `1vh` is `H/100`, so raising H grows that element too and content stays pinned to the328 canvas bottom at *every* H. Discriminate once by rendering at a clearly different H and329 comparing the reported content bottom: unchanged means it was real truncation and is now330 fixed; still ≈ the new canvas height means it is the `vh` loop. Do not keep doubling H —331 an operator who sees the same warning at 3000 and at 40000 learns to ignore it, and a332 gate trained into noise no longer catches the real truncation it exists for.333334 Also test the narrow-screen layout with real device emulation and measure overflow.335 Device emulation is not optional phrasing: headless Chrome clamps `--window-size` to a336 ~500 CSS px minimum width (measured 2026-09-17: asking 390 yields `innerWidth=500`;337 `--force-device-scale-factor` does not shrink the CSS viewport either). For 390-class338 phone widths use Playwright/CDP `Emulation.setDeviceMetricsOverride` (or Ego) — never339 report a `--window-size=390` run as a phone-width test.340341 Measuring painted bar spans for the proportion gate: anchor on the *container* (find the342 track box first, then measure dark pixels inside it), never cluster content pixels343 globally — edge antialiasing creates phantom clusters and a long bar hides its own track344 row (two real failures from 2026-09-17).3457. **Exercise the journey.** In a real browser, follow the reader's route—not merely346 a click list. Test understanding order, the obvious next action, keyboard access,347 modal focus, deep links, filters, and error/empty states. Use348 `frontend-visual-qa` for micro, macro, and intent review. Every shelf component you349 embedded gets its primary interaction clicked here, and you write down what you350 observed — "the drawer opened and highlighted clause 7" is evidence; "the component351 is present" is not. Check that actual images load, important details are readable,352 captions remain next to their visuals, and the delivered local file has no missing assets.3538. **Reconcile and verify.**354355 For a merge or a current-state update, apply the semantic acceptance contract in356 `references/long-lived-report-maintenance.md` §6.1. Keep the information-point357 mapping with the gate evidence; a source-link index is not the requested synthesis.358359 - For a rewrite or merge, run:360361 ```bash362 uv run --python 3.12 python <skill-dir>/scripts/reconcile_content_diff.py old.html new.html363 ```364365 It opens both pages in Chrome and compares their initial, computed reader-visible366 text. This does not traverse tabs/accordions or other interaction-created states;367 cover those states in the Journey/browser harness.368 - For generated long-lived pages, run the page generator and then its `--check`369 mode. Missing/duplicate anchors or stale output are failures.370 - Search for stale facts, shorthand, unsupported claims, broken file paths, and371 duplicated version/status values.3729. **Independent reader review — and leave a file saying it happened.** The reviewer373 must start with no inherited conversation or author reasoning: in Codex use374 `fork_turns: "none"`; in Claude Code start a separate non-fork `general-purpose`375 agent and put all required reader context in its prompt. Give that reviewer the HTML plus its376 rendered screenshots — and nothing else (the table below says "the page and nothing else";377 screenshots are the page, a text-only reviewer answers the visual questions by reading378 source, which is indistinguishable in the write-up from having looked), using379 `references/independent-review-prompt.md` verbatim. Reader comprehension failures380 are defects — with one exception, `读者已知清单` below, that a page not declaring a381 narrow audience never gets to claim. Treat proposed implementation changes as382 hypotheses and reproduce them before changing the artifact.383384 Confirm the reviewer can actually open a browser before you send it the page — several385 of the review questions are about focus, Escape and keyboard order, and a text-only386 reviewer will answer them by reading the source. You cannot introspect a subagent's387 capabilities before spawning it, so make it the reviewer's own first action: tell it to388 attempt the browser step and **report "browser unavailable — items 7 and 8 answered from source"389 in its output** if it cannot. An unmarked source-read answer is the failure; a marked one390 is a known gap you can cover another way. That answer is indistinguishable in391 the write-up from one produced by clicking, and it lands in exactly the blind spot this392 skill warns about: every static check passes while the feature does nothing.393394 Write the outcome to a file next to the page (or in your review archive): **how the395 reviewer was spawned (agent type, and that it was not a fork)**, the prompt you gave,396 each finding with its disposition and reason, and what could not be checked. Record the397 spawn details because a fork's write-up reads identically to an independent one — the398 only thing that distinguishes them is a fact about how it was launched, and if that is399 never written down, the independence requirement above is unverifiable by anyone400 including you. The file itself is the point: a review that leaves nothing behind is401 indistinguishable from a review you meant to run and didn't, and that is the failure402 mode this step actually has. It is not that authors disagree with the step; it is403 that under delivery pressure the step is the cheapest thing to silently drop.404405 **Triage every "I don't understand this" finding against `读者已知清单` before it counts —406 provisionally; step 10 independently re-derives it, this isn't a self-check.** The407 reviewer's zero-context persona is deliberate and does not change — but a term that is on408 the list committed in step 1 is a **phantom problem** (Sauro, MeasuringU): the reviewer409 correctly has no way to know it, and the declared audience isn't actually confused by it.410 Quote the reviewer's finding **verbatim** next to the list entry it's disposed against —411 "reduces to a known term" is an interpretive claim, not a file-exists check, and the quote412 is what lets someone other than you judge whether the reduction was honest. Log the413 disposition as `audience-declared-known` with that quote and reason; it does not count414 toward the same-axis-recurrence test below. A flagged term that is *not* on the list either415 stands as a real finding, unchanged from today, or gets added now — in which case say so416 directly in the gate file next to the entry (`补记于 cycle N 审阅之后`) rather than blending417 it into the original list silently. Do not backdate it: `init --force`'s preserved418 "上一轮的答案" appendix already carries the list as it stood before this cycle, so a419 silently-blended addition is trivially caught by diffing the current list against that420 appendix — say it plainly instead of relying on someone doing that diff. Full mechanism and421 the grounding for why this pass is provisional rather than final are in422 `references/audience-triage.md`.423424 **Deciding whether to run it again is an observation about invalidated evidence, not an425 edit count.** Compare the delta with the claims and reader decisions the recorded review426 covered. A number, term, or label change triggers a fresh page-only review only when it427 invalidates the previous reader's interpretation of an affected claim, visual encoding,428 layout, interaction, or decision structure; not every number or term change does. Reuse429 unrelated review evidence when its input, configuration, criterion, and relevant state430 are unchanged and no new failure signal exists. A local NAS-name correction, a431 normalized-copy hash label, or an actionable gap-card correction requires readback of432 every affected projection and its meaning, not another unchanged full QA pass. Typo and433 punctuation fixes need only the affected readback. Chart, layout, or interaction changes434 require a fresh render and rechecks of the affected axes. Stop once the named finding is435 resolved; do not dispatch a new reviewer just because its small fix landed.436437 **A required re-review has no ceiling of its own — pair it with a budget, or "any438 invalidating edit needs review" mints an unbounded stream of fresh rounds.** A local fix439 whose affected readback resolves the named finding without invalidating the blind read440 does not start another cycle. When re-review is required, a converging review and a441 runaway one are indistinguishable from inside a single round — the failure has been442 observed at both small scale (three full rounds to close one low-stakes correction) and443 large (21 rounds on a real decision document, stopped only because a human asked why).444 This is the Loop Contract from445 `claude-code-hooks`'s SKILL.md rule 7 — "If the hook demands remediation, prove the446 loop terminates"447 (`daymade-claude-code/claude-code-hooks/SKILL.md` (daymade/claude-code-skills),448 read there for the general framework and its worked failure cases) — instantiated for449 this step instead of a hook:450451 ```text452 LOOP KEY: this delivery's lineage (the HTML frozen at round 1 plus every descendant453 edit) + one failure axis: can a fresh, uninformed reader use this page?454 FIRE T: after audience triage (above), a review still answers review-prompt item 9455 "no" — or surfaces any finding that amounts to the same thing (the reader456 could not actually make the decision this page exists to produce) — on that457 same axis, using only findings that survived triage458 REMEDIATION R: reproduce the finding, apply one bounded fix, and read back every affected459 projection and its meaning; re-run the blind review once only if that460 delta invalidates its axis461 VARIANT V: 2 - completed review cycles for this lineage462 BUDGET: 2 cycles total — the initial review plus one narrowly scoped re-review.463 A third reviewer on this lineage is never automatic.464 SUCCESS EXIT: the affected readback resolves the named finding without invalidating465 existing blind-read evidence; otherwise the single re-review answers item 9466 "yes" on that same axis, with nothing else reopening it467 AUDIENCE-MISMATCH EXIT: EVERY SINGLE post-triage reason behind a cycle's "no" disposes as468 audience-declared-known — ship, log the disposition table, do not report this469 to the user as blocked. "Every" means every: a "no" with two reasons, one470 audience-related and one a genuine unrelated defect (a chart missing a unit, a471 broken cross-reference), is not this exit — the unrelated reason alone routes472 through ordinary REMEDIATION/CAPPED EXIT, same as if it had appeared by itself.473 This can fire after cycle 1 alone: if nothing survived triage, there is no474 finding for REMEDIATION to reproduce and fix, so a mandatory cycle 2 would just475 re-review an unchanged page for a second phantom verdict.476 (see `references/audience-triage.md`)477 CAPPED EXIT: at least one post-triage finding is real and recurring across two cycles —478 stop, report the remaining findings as a backlog, do not ship silently, and do479 not dispatch a third reviewer on your own authority480 ```481482 This skill's own reviewer output has no severity vocabulary to key off — the review483 prompt (`references/independent-review-prompt.md`) returns answered questions, not484 BLOCKER/MAJOR-rated findings, and step 10's acceptance vocabulary is PASS / FAIL /485 CANNOT-CHECK — so FIRE T and SUCCESS EXIT above are keyed to review-prompt item 9's own486 "最后一问" answer (can the reader act on this page with no other explanation?) rather487 than to rule 7's example severity labels, which describe a different kind of review and488 don't otherwise appear anywhere in this skill.489490 **A same-axis recurrence and a new, unrelated finding get different treatment on491 cycle 2** — conflating them is what turns a bounded loop into an expanding one. Apply492 the audience triage above to each cycle's findings first; everything below is about493 what survives it. If cycle 1's findings dispose entirely as audience-declared-known,494 take the AUDIENCE-MISMATCH EXIT right there — there is nothing left for cycle 2 to495 re-review.496 - Cycle 2 reproduces a comprehension failure **on the same axis** cycle 1 already497 named (the reader still can't use the page, even if the specific wording changed) →498 that is the CAPPED EXIT above **only if the finding survived triage**. If both499 cycles' reasons dispose entirely as audience-declared-known, that is the500 AUDIENCE-MISMATCH EXIT instead — ship, don't report blocked. When a real,501 post-triage finding does recur: stop. Report `blocked`. Do not reason "but this502 finding is real" into a third dispatch — realness was never the missing check; a new503 user-authorized task with its own predeclared budget is what's missing, and only the504 user can open one.505 - Cycle 2 surfaces something **genuinely new and unrelated** (cycle 1 was about a506 decision card's clarity; cycle 2 incidentally flags an unrelated color problem) →507 record it as a separate backlog item for a separate task. It does not consume this508 lineage's budget and, by itself, is not grounds for a cycle 3 on this lineage — ship509 what converged, and open the new item as its own review with its own budget if the510 user wants it pursued now.511512 **Stop after the named result is decided.** Once steps 9/10 have returned the verdict for513 the current delta, do not reopen them merely because a small accepted fix landed. A later514 maintenance delta selects its own bounded evidence under §6.3; only invalidated axes are515 rechecked. A third reviewer on the same unresolved comprehension lineage is still never516 automatic.51710. **Independent acceptance.** Either hand the acceptance checklist below, the page and its518 sources, and the original request, later corrections, output contract and required519 acceptance criteria to a *second* fresh-context agent, or use the step 9 independent agent520 after its page-only blind read has been returned and frozen. The latter is the sequential521 route defined at Workflow entry, not permission to leak sources, author findings, or522 proposed fixes before that freeze. Keep the two phases separate because they answer523 different questions (see the table under that list). The acceptance phase returns a verdict524 and evidence per item. Its FAILs are findings you reproduce and fix, exactly like step 9's;525 its PASSes are the only thing that closes an item.52611. **Finalize after review.** Apply accepted fixes, then select only checks invalidated by527 the actual changed axes. Re-render and recheck affected visual, layout, or interaction axes528 after chart, layout, or interaction changes; rerun only affected journeys and masked/gate529 artifacts. For a local text-only delta, read back every affected projection and its meaning.530 If a particular gate or check is inapplicable to that delta, record531 `inapplicable: <reason>` and the relevant readback; never describe a stale gate as green.532 If the page contract or repository still requires a check, run it. For an invalidated533 delivery gate, re-run `init --force`, read the new masked render, carry forward only answers534 confirmed against it, then run `check` again. Reuse unrelated evidence only while its535 inputs, configuration, criteria, and relevant state remain unchanged and no new failure536 signal exists. Only then open the final HTML for the user. Do not open a pre-review draft537 as the delivered artifact.538539**Where a new lesson goes — answer in this order before writing one into this skill.**540541**First: was the failure *"I forgot to do it"* or *"I did it and could not see it was542wrong"*?** The first belongs in the workflow above; a reminder solves it. The second has to543become a question somebody **else** asks, because the author did not skip it — they looked544straight at it and judged it fine. Colour, terminology, whether a chart supports its own545caption, whether a decision card is missing an option: all of the second kind. Putting546those on a list the author answers is exactly how a rule ends up written down *and still547violated* — which is what happened to every rule this skill had to relearn the hard way.548549**Then, if it is somebody else's question: can it be answered from the page alone?**550Yes → the reader's prompt (`references/independent-review-prompt.md`). No → the acceptance551list below. That second question is what keeps the two lists from growing copies of each552other; the table below states the same boundary from the other side.553554## Delivery acceptance — an independent agent runs this list, not you555556Reader review and acceptance close a delivery, and **they do not overlap**: every check lives in557exactly one of them, so there is nothing for them to drift apart on.558559| | step 9 · reader review | step 10 · acceptance |560|---|---|---|561| gets | **the page and nothing else** (screenshots count as the page) | the page **plus** the original request and corrections, output contract and required acceptance, your sources, commands, review file, **and the gate artifacts** |562| asks | can you read it? can you decide from it? | does it deliver the requested result, and does what is off the page agree with what is on it? |563| its questions live in | `references/independent-review-prompt.md` — all of them, used verbatim | the items below |564| authority | everything visible on the page | original task requirements, provenance and process |565566**The split rule, so a future addition lands in one place instead of both:** does answering567it require something *outside* the page? **No → it is a reader question**; add it to the568review prompt. **Yes → it belongs here.** Colour, wording, whether a chart supports its own569caption, whether a decision card is missing an option, whether the headings form an570argument — all visible on the page, all the reader's. The checks below need what the571reader does not have.572573Hand this list, the page **and its gate artifacts** (`page.html.gate.md`, `page--masked.png`),574the original request and later corrections with their source coordinates, the existing output575contract and required acceptance criteria, the sources behind load-bearing facts, the commands576you ran, and the step 9 review file to the acceptance agent selected in step 10. You may walk it yourself first — it catches the577obvious misses cheaply — but *you do not get to declare the items passed.*578579Why it cannot be a self-check, stated plainly because the urge to skip it peaks exactly580when delivery is close: an earlier version of this list asked the author to "be able to581point to" each item, which they could always sincerely claim. Rewriting it to demand pasted582evidence fixed half the problem — the evidence now exists — and left the other half, because583the author still ruled on whether their own evidence sufficed. The failures behind these584items were all that shape: a chart its author found perfectly clear, a colour scheme they585had considered and approved, a recommendation whose missing downside they never noticed.586None was a forgotten step. Reminders do not reach errors like these; a second pair of eyes587does.588589Ask for: item number, PASS / FAIL / CANNOT-CHECK, and the specific evidence — a quoted590line, a count, a command's output. An item that cannot be checked is reported as such,591never as a pass.5925930. **Requested result** — the existing acceptance agent first maps each required reader594 question or output to its answer and evidence in the delivered page, quoting the requirement595 and the page location. Missing answers or a sample/prototype substituted for a required596 report are FAILs even when interactions, rendering and gates pass. A sample-only request is597 judged against that scope; do not require a full report it never requested. Missing original598 requirements are CANNOT-CHECK; do not infer them from the author's narrower contract.599 This is semantic acceptance, not something the delivery-gate script establishes.6001. **Provenance** — every load-bearing fact traces to a source *outside* the page, with an601 as-of date: not only numbers, but quoted clauses, claims about what someone agreed to,602 statements about a dependency's status. The reader can check a page against itself;603 only this pass can check it against the world. Anything untraceable is removed from the604 page or visibly marked unknown.605 For sourced images, match the actual file to its original publisher and ex606607…(truncated)