Website review — Double-Knuth (correctness + consistency)
A two-pass audit of a site's code/config/content, modelled on the
portfolio-code-reviewer Double-Knuth. It sits on top of website-qa: the
tests are the floor (must be green first); this is the human-grade review that
catches what a test suite can't — cross-file drift and half-done work.
When to run
- End of a build, before launch (pipeline step 8).
- After adding or substantially editing a page — a new route touches
PAGES,
nav, the sitemap, internal links and canonical, so consistency can silently break.
- It is read-only: produce a ranked list, then fix BUGs before launch. Don't
fix-and-forget — surface first (Rule 12: never hide a skipped or broken thing).
- For just "is the offer clear to a stranger" on a site that's already built —
faster and narrower than this full audit — use
website-positioning-check.
Review depth — the owner chooses, every time
A website is lower-stakes than application code: a subtle bug in a landing
page's copy costs a bad reading experience, not a broken payment or a data
leak. This skill (Double-Knuth, below) is free, runs entirely in the current
session, and is the default, sufficient review for the large majority of
website changes — new pages, copy edits, layout tweaks, small SEO
adjustments, content updates. An external AI reviewer on top of it is an
optional extra, never a requirement, and never more than one at a time.
Default — no setup, no cost, use this unless there's a specific reason not to:
- This skill, both passes — Pass 1 delegates to
/code-review
(correctness bugs), Pass 2 is the cross-file/consistency sweep below.
/code-review alone — just Pass 1, for a small, self-contained diff
where cross-file consistency clearly isn't at risk (a one-page copy fix, a
single component tweak). Faster than the full two-pass audit when that's
all the change touches.
Optional escalation — one external reviewer, only when it's genuinely worth it:
A handful of website changes carry enough risk that a second, independent
model is worth the extra step: a site-wide SEO repositioning (the
seo-reposition skill's plan/diff gates), a payment or checkout flow, a
form collecting sensitive personal data, or a major structural
redesign where the author reviewing their own architecture risks sharing
its blind spots. Even for these, use one external reviewer, not the
independent-review skill's own default of two — that default is calibrated
for production application code (Rails migrations, auth changes), not
website content/structure work:
# from this repo's skills root, or the equivalent path in a site that has
# independent-review vendored in:
skills/independent-review/scripts/independent_review.sh <file> --plan --first-success # or --diff
A --diff run first checks the diff against git, from the repository it came from: a diff
git diff made from the merge base with the default branch passes as it is; a diff of only some
commits names its start with --base <commit>, and one not made by git diff there passes
--base none (independent-review's script header, BASE CHECK).
--first-success stops at the first reviewer that answers (Codex CLI,
falling back to ollama-cloud) instead of running both — independent-review
honors this override for plans, it doesn't force the pair. Setup: if
independent-review isn't already working in this repo, its own SKILL.md
has a guided onboarding wizard for getting Codex or ollama-cloud running
(free, no payment) — walk through that first rather than assuming it's ready.
In a scaffolded site the skill isn't shipped at all: check that the
independent-review folder actually exists before offering this escalation
as ready-to-run. If it doesn't, either vendor it first (copy
skills/independent-review/ from the Croftweaver suite — the same kit
this skill was copied from — into the site's .claude/skills/; a plugin
installed from Anthropic's directory leaves that folder out, so then take it
from https://github.com/karero/croftweaver) or frame the
offer honestly as "available after a one-time setup step".
Explain the choice, then ask — don't decide silently. Before reaching for
anything beyond this skill's own two passes, say plainly what the options
are and what's actually at stake: "I can review this with the built-in
check — free, runs now — or also send it to an outside AI for a second
opinion, which costs nothing either but takes a few extra minutes. For
[this kind of change] I'd lean toward
[recommendation] because [reason] — want that, or would you rather [the
other option]?" The owner decides; this skill's job is to make an informed
recommendation, never to pick unasked.
Pass 1 — correctness / bugs
- Run
/code-review on the branch/diff (correctness bugs + reuse/simplification).
/code-review is Claude Code-only — under another host, review the diff by
hand against this pass's checklist, or vendor the generic double-knuth
skill from the Croftweaver suite.
npm run build is clean — no errors or warnings; TS strict passes.
npm test green (the starter's whole suite, tests/*.spec.ts) — nothing skipped or loosened. (A site scaffolded before a spec existed: copy it in from the starter rather than reviewing without it. placeholders.spec.ts goes in with its UNFILLED_UNTIL_LAUNCH as shipped, on a launched site too: the first run names each entry to delete, and its check for lower-case slots, which runs on listed pages only, finds the one older starters carried on the privacy page. placeholders.spec.ts also fails on a legal page with no recorded answer in the README.md, unless that page is still listed and shows its draft notice: ask the owner as AGENTS.md §5 says.)
astro preview the new/edited pages — no console errors; interactions work.
- Nothing half-done: no TODO/placeholder/lorem and no leftover
[BRACKET] slots in shipped
pages OR public/ assets. placeholders.spec.ts enforces this on the rendered pages and
the manifest; read for what it cannot see: pages outside PAGES (the 404 page, noindex
pages), other public/ files (llms.txt and its own slots included), PDFs, text inside
images, the starter's example values, and an entry still sitting in its
UNFILLED_UNTIL_LAUNCH at launch (it only warns there).
- Freshness date matches the edit: if the page's visible content changed and it carries a
last-modified signal (a
dateModified/"Updated" byline, an Article/BlogPosting JSON-LD date),
that date is bumped to today. It silently drifts otherwise — stale in the visible byline, the
<time datetime> attribute, and the schema's dateModified (an SEO/AI-answer-engine freshness
signal) all at once, and no test catches it because nothing can know a date is "wrong" without
knowing the edit happened.
- Nothing silently unshipped (two-stage sites):
git log origin/production..origin/main empty,
or the gap is a conscious decision — and the last npm run ship ended "✓ LIVE — verified".
Any deploy you run or announce follows the site's PUBLISHING.md § "For AI assistants —
deploy-time guardrails" (preview-vs-live announcements + the cached-404 rule).
Pass 2 — completeness + cross-file/skill consistency
- Routes: every
src/pages/** route is in tests/_helpers.ts PAGES (and vice-versa;
seo.spec.ts's sitemap drift alarm enforces it); nav + every internal link points to a real
route; every route is reachable via at least one inbound internal link (no orphan pages —
the privacy page included).
- URLs: the no-trailing-slash convention holds everywhere (
/about, not /about/);
canonical == og:url == SITE.url + path.
- Single source of truth: address, email, phone, nav come only from
src/config.ts —
no hardcoded copies drifting inside pages.
- Recurring section patterns carry consistent headings: if a component pattern (e.g. a
grid grid-2/grid-3 card block) has its own <h2> directly above it everywhere else it
appears on the site, a new or edited instance should too. A local heading step (h2 → h3) will
not trip axe's heading-order rule, so this only surfaces by checking this page's heading
structure against how the same pattern is used on other pages, not by trusting the a11y suite.
- SEO (
website-seo-geo): title ≤60, description 120–160, og/twitter mirror, exactly one
<h1>, JSON-LD valid, sitemap covers every page, llms.txt current.
- Images (
website-design-system): WebP/AVIF, explicit width/height, alt; the LCP
image eager (fetchpriority="high"), below-fold lazy; no oversized files.
- Email: every address rendered via
<EmailLink>; email.spec.ts green.
- Headers/redirects:
_headers CSP present; legacy URLs 301 in _redirects. A Worker
site: wrangler.jsonc has workers_dev: false and no main (workers-config.spec.ts
checks it). A site still on Pages: the *.pages.dev middleware in place (previews
noindexed), and on a launched site the project's own pages.dev address (as Cloudflare
shows it; not always the project's name) answers 301 to the live domain — if it answers
200, see
the causes listed in new-website/references/CLOUDFLARE_FIRST_DEPLOY.md, "After
go-live", step 3 (variable not under Production or rejected, no redeploy since, or a
middleware that predates the redirect).
- Secrets: no
.env/token committed; .gitignore covers them.
- Docs match code: README test list + "how to add a page / run tests / deploy" current;
CONTENT_GUIDE.md + BRAND.md filled (+ STORY.md, consistent with POSITIONING.md,
if the site opted into website-story); decision-interview answers recorded; the handoff
skill set present in .claude/skills/.
- Language/i18n (non-English or multi-locale sites): every page's CONTENT language
matches its
<html lang> (the tone gate's density check covers German; eyeball other
languages); og:locale present and matching on every page; chrome (skip link, footer)
in the site's language; German-market sites carry the filled imprint (/legal-notice; /impressum
on a German-language site, /de/impressum multilingual) and the German
privacy page at the right URL (/datenschutz single-locale, /de/privacy multilingual);
multi-locale sites: hreflang sets complete + reciprocal (tests/i18n.spec.ts green, or
the twin-page seo.spec test for the light path), every /locale route in PAGES, the
language switcher on every multi-locale page, llms.txt entries in each page's language.
Output / done means
A ranked BUG / RISK / NIT list, each with file:line and a concrete fix (same shape as
the portfolio Double-Knuth). Fix BUGs before launch; RISK/NIT by judgment. Re-run website-qa
after fixes. Done = both passes clean, or the remaining items explicitly listed — never hidden.
1---2name: website-review3description: >4 The Double-Knuth review for a site — a two-pass correctness + cross-file5 consistency audit run at the END of a build (pre-launch) and after ADDING or6 substantially editing a page.7 Pass 1 = bugs/correctness (delegates the diff to /code-review);8 Pass 2 = completeness + route/URL/SEO/config/email/docs consistency against9 the site contract. Read-only: returns a ranked BUG/RISK/NIT list with10 file:line + fixes. Prerequisite: website-qa green. Also owns the "review11 depth" decision for website work — when this free default suffices vs. an12 owner-approved single external reviewer for genuinely higher-stakes changes13 (its "Review depth" section has the rule). Trigger phrases: "double-knuth",14 "double knuth the site", "review the site", "site review", "final review15 before launch", "review this page", "did adding the page break anything",16 "consistency check the site", "audit the site code", "how much review does17 this need", "do I need a second opinion on this", "should I use18 independent-review for this".19metadata:20 source: https://skillmd.com/skills/karero/website-review21---2223# Website review — Double-Knuth (correctness + consistency)2425A two-pass audit of a site's code/config/content, modelled on the26`portfolio-code-reviewer` Double-Knuth. It sits **on top of `website-qa`**: the27tests are the floor (must be green first); this is the human-grade review that28catches what a test suite can't — cross-file drift and half-done work.2930## When to run31- **End of a build, before launch** (pipeline step 8).32- **After adding or substantially editing a page** — a new route touches `PAGES`,33 nav, the sitemap, internal links and canonical, so consistency can silently break.34- It is **read-only**: produce a ranked list, then fix BUGs before launch. Don't35 fix-and-forget — surface first (Rule 12: never hide a skipped or broken thing).36- For just "is the offer clear to a stranger" on a site that's already built —37 faster and narrower than this full audit — use `website-positioning-check`.3839## Review depth — the owner chooses, every time4041A website is lower-stakes than application code: a subtle bug in a landing42page's copy costs a bad reading experience, not a broken payment or a data43leak. This skill (Double-Knuth, below) is free, runs entirely in the current44session, and is **the default, sufficient review for the large majority of45website changes** — new pages, copy edits, layout tweaks, small SEO46adjustments, content updates. An external AI reviewer on top of it is an47*optional* extra, never a requirement, and never more than one at a time.4849**Default — no setup, no cost, use this unless there's a specific reason not to:**50- **This skill, both passes** — Pass 1 delegates to `/code-review`51 (correctness bugs), Pass 2 is the cross-file/consistency sweep below.52- **`/code-review` alone** — just Pass 1, for a small, self-contained diff53 where cross-file consistency clearly isn't at risk (a one-page copy fix, a54 single component tweak). Faster than the full two-pass audit when that's55 all the change touches.5657**Optional escalation — one external reviewer, only when it's genuinely worth it:**58A handful of website changes carry enough risk that a second, independent59model is worth the extra step: a **site-wide SEO repositioning** (the60`seo-reposition` skill's plan/diff gates), a **payment or checkout flow**, a61form collecting **sensitive personal data**, or a **major structural62redesign** where the author reviewing their own architecture risks sharing63its blind spots. Even for these, use **one** external reviewer, not the64`independent-review` skill's own default of two — that default is calibrated65for production application code (Rails migrations, auth changes), not66website content/structure work:67```bash68# from this repo's skills root, or the equivalent path in a site that has69# independent-review vendored in:70skills/independent-review/scripts/independent_review.sh <file> --plan --first-success # or --diff71```72A `--diff` run first checks the diff against git, from the repository it came from: a diff73`git diff` made from the merge base with the default branch passes as it is; a diff of only some74commits names its start with `--base <commit>`, and one not made by `git diff` there passes75`--base none` (independent-review's script header, BASE CHECK).76`--first-success` stops at the first reviewer that answers (Codex CLI,77falling back to ollama-cloud) instead of running both — independent-review78honors this override for plans, it doesn't force the pair. Setup: if79`independent-review` isn't already working in this repo, its own SKILL.md80has a guided onboarding wizard for getting Codex or ollama-cloud running81(free, no payment) — walk through that first rather than assuming it's ready.82In a scaffolded site the skill isn't shipped at all: check that the83`independent-review` folder actually exists before offering this escalation84as ready-to-run. If it doesn't, either vendor it first (copy85`skills/independent-review/` from the Croftweaver suite — the same kit86this skill was copied from — into the site's `.claude/skills/`; a plugin87installed from Anthropic's directory leaves that folder out, so then take it88from https://github.com/karero/croftweaver) or frame the89offer honestly as "available after a one-time setup step".9091**Explain the choice, then ask — don't decide silently.** Before reaching for92anything beyond this skill's own two passes, say plainly what the options93are and what's actually at stake: *"I can review this with the built-in94check — free, runs now — or also send it to an outside AI for a second95opinion, which costs nothing either but takes a few extra minutes. For96[this kind of change] I'd lean toward97[recommendation] because [reason] — want that, or would you rather [the98other option]?"* The owner decides; this skill's job is to make an informed99recommendation, never to pick unasked.100101## Pass 1 — correctness / bugs102- Run **`/code-review`** on the branch/diff (correctness bugs + reuse/simplification).103 `/code-review` is Claude Code-only — under another host, review the diff by104 hand against this pass's checklist, or vendor the generic `double-knuth`105 skill from the Croftweaver suite.106- `npm run build` is clean — no errors **or warnings**; TS strict passes.107- `npm test` green (the starter's whole suite, `tests/*.spec.ts`) — nothing skipped or loosened. (A site scaffolded before a spec existed: copy it in from the starter rather than reviewing without it. `placeholders.spec.ts` goes in with its `UNFILLED_UNTIL_LAUNCH` as shipped, on a launched site too: the first run names each entry to delete, and its check for lower-case slots, which runs on listed pages only, finds the one older starters carried on the privacy page. `placeholders.spec.ts` also fails on a legal page with no recorded answer in the `README.md`, unless that page is still listed and shows its draft notice: ask the owner as `AGENTS.md` §5 says.)108- `astro preview` the new/edited pages — **no console errors**; interactions work.109- Nothing half-done: no TODO/placeholder/lorem and no leftover `[BRACKET]` slots in shipped110 pages OR `public/` assets. `placeholders.spec.ts` enforces this on the rendered pages and111 the manifest; read for what it cannot see: pages outside `PAGES` (the 404 page, noindex112 pages), other `public/` files (`llms.txt` and its own slots included), PDFs, text inside113 images, the starter's example values, and an entry still sitting in its114 `UNFILLED_UNTIL_LAUNCH` at launch (it only warns there).115- **Freshness date matches the edit:** if the page's visible content changed and it carries a116 last-modified signal (a `dateModified`/"Updated" byline, an Article/BlogPosting JSON-LD date),117 that date is bumped to today. It silently drifts otherwise — stale in the visible byline, the118 `<time datetime>` attribute, and the schema's `dateModified` (an SEO/AI-answer-engine freshness119 signal) all at once, and no test catches it because nothing can know a date is "wrong" without120 knowing the edit happened.121- Nothing silently unshipped (two-stage sites): `git log origin/production..origin/main` empty,122 or the gap is a conscious decision — and the last `npm run ship` ended "✓ LIVE — verified".123 Any deploy you run or announce follows the site's `PUBLISHING.md` § "For AI assistants —124 deploy-time guardrails" (preview-vs-live announcements + the cached-404 rule).125126## Pass 2 — completeness + cross-file/skill consistency127- **Routes:** every `src/pages/**` route is in `tests/_helpers.ts` `PAGES` (and vice-versa;128 seo.spec.ts's sitemap drift alarm enforces it); nav + every internal link points to a real129 route; every route is reachable via at least one inbound internal link (no orphan pages —130 the privacy page included).131- **URLs:** the no-trailing-slash convention holds everywhere (`/about`, not `/about/`);132 `canonical == og:url == SITE.url + path`.133- **Single source of truth:** address, email, phone, nav come **only** from `src/config.ts` —134 no hardcoded copies drifting inside pages.135- **Recurring section patterns carry consistent headings:** if a component pattern (e.g. a136 `grid grid-2`/`grid-3` card block) has its own `<h2>` directly above it everywhere else it137 appears on the site, a new or edited instance should too. A local heading step (h2 → h3) will138 not trip axe's heading-order rule, so this only surfaces by checking this page's heading139 structure against how the same pattern is used on other pages, not by trusting the a11y suite.140- **SEO (`website-seo-geo`):** title ≤60, description 120–160, og/twitter mirror, exactly one141 `<h1>`, JSON-LD valid, sitemap covers every page, `llms.txt` current.142- **Images (`website-design-system`):** WebP/AVIF, explicit `width`/`height`, `alt`; the LCP143 image eager (`fetchpriority="high"`), below-fold lazy; no oversized files.144- **Email:** every address rendered via `<EmailLink>`; `email.spec.ts` green.145- **Headers/redirects:** `_headers` CSP present; legacy URLs 301 in `_redirects`. A Worker146 site: `wrangler.jsonc` has `workers_dev: false` and no `main` (`workers-config.spec.ts`147 checks it). A site still on Pages: the `*.pages.dev` middleware in place (previews148 noindexed), and on a launched site the project's own `pages.dev` address (as Cloudflare149 shows it; not always the project's name) answers 301 to the live domain — if it answers150 200, see151 the causes listed in `new-website/references/CLOUDFLARE_FIRST_DEPLOY.md`, "After152 go-live", step 3 (variable not under Production or rejected, no redeploy since, or a153 middleware that predates the redirect).154- **Secrets:** no `.env`/token committed; `.gitignore` covers them.155- **Docs match code:** README test list + "how to add a page / run tests / deploy" current;156 `CONTENT_GUIDE.md` + `BRAND.md` filled (+ `STORY.md`, consistent with `POSITIONING.md`,157 if the site opted into `website-story`); decision-interview answers recorded; the handoff158 skill set present in `.claude/skills/`.159- **Language/i18n (non-English or multi-locale sites):** every page's CONTENT language160 matches its `<html lang>` (the tone gate's density check covers German; eyeball other161 languages); `og:locale` present and matching on every page; chrome (skip link, footer)162 in the site's language; German-market sites carry the filled imprint (`/legal-notice`; `/impressum`163 on a German-language site, `/de/impressum` multilingual) and the German164 privacy page at the right URL (`/datenschutz` single-locale, `/de/privacy` multilingual);165 multi-locale sites: hreflang sets complete + reciprocal (`tests/i18n.spec.ts` green, or166 the twin-page seo.spec test for the light path), every `/locale` route in PAGES, the167 language switcher on every multi-locale page, llms.txt entries in each page's language.168169## Output / done means170A ranked **BUG / RISK / NIT** list, each with `file:line` and a concrete fix (same shape as171the portfolio Double-Knuth). Fix BUGs before launch; RISK/NIT by judgment. Re-run `website-qa`172after fixes. **Done = both passes clean**, or the remaining items explicitly listed — never hidden.