Skip to content

Commit a708c36

Browse files
remigiusz-antczakRemigiusz Antczakclaude
authored
feat(skill): 1.77.0 — wave 6 design-parity verification lenses (#169, #170, #171, #177, #178) (#183)
Five lenses on how to VERIFY an implementation against a design without rubber-stamping a mismatch. Each points at existing parity content rather than restating it (anti-duplication thesis): - product-ux-quality.md: a parity differ as a 4th Phase-6 enforcing gate — build a mechanical comparator before pixel-matching, gate every "matches" on its diff image + structured mismatch list (never a sentence); it proves equivalence, not that someone looked, and states what it cannot prove (#177). Read the reference at highest fidelity: running build > design source > screenshot (#169). Classify structural vs cosmetic, structural parity first, never call a structural divergence "close / 1:1" (#170). Repeated correction of a "matches" claim means the verification method is broken — build the comparator (#171). - migration-parity.md: match the chrome, never the mock's data — copying a mock's sample value into the product is fabrication (principle 3), a Blocker (#178). The four-axes structure/styling split was sharpened so presence is structural and rendered look is cosmetic (one taxonomy, resolving a severity seam #170 introduced). Three new behavioral evals; new parity flags; one checklist line. Lockstep bump to 1.77.0; SHA256SUMS regenerated. An independent dogfood reviewer ran the suite's own method on the diff and caught a Major (the same diff classified into two axes with different severity) plus four Minors — all fixed pre-commit. Closes #169, #170, #171, #177, #178. Co-authored-by: Remigiusz Antczak <remigiusz@antczak.io> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 5f7285c commit a708c36

12 files changed

Lines changed: 179 additions & 26 deletions

File tree

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "deep-code-review",
33
"description": "Perun — bring the thunder to your codebase. A portable, evidence-grounded quality bar for building with AI agents: the flagship deep-code-review skill (default install is review-only), plus opt-in overlays — gated delivery, an idea critic, a suite conductor, and stage-aware product, growth, positioning, business-ops, and output-safety specialists.",
44
"skills": "./.claude/skills",
5-
"version": "1.76.0",
5+
"version": "1.77.0",
66
"author": {
77
"name": "deep-code-review contributors"
88
},

‎.claude/skills/agentic-delivery/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ description: >-
1010
license: MIT
1111
metadata:
1212
author: deep-code-review contributors
13-
version: "1.76.0"
13+
version: "1.77.0"
1414
---
1515

1616
# Agentic delivery
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.76.0
1+
1.77.0

‎.claude/skills/deep-code-review/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ description: >-
1111
license: MIT
1212
metadata:
1313
author: deep-code-review contributors
14-
version: "1.76.0"
14+
version: "1.77.0"
1515
---
1616

1717
# Deep Code Review
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.76.0
1+
1.77.0

‎.claude/skills/deep-code-review/evals/evals.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -625,6 +625,38 @@
625625
"Requires distinguishing no-data-collected/covered from collected-and-genuinely-none",
626626
"Requires the empty state to name coverage (was the source actually probed), not imply a false all-clear"
627627
]
628+
},
629+
{
630+
"id": "parity-claim-gated-on-mechanical-differ",
631+
"prompt": "The approved design ships in the repo as a runnable prototype. The agent rebuilt each screen to match it and reports 'pixel-1:1, matches' after glancing at a screenshot. The reviewer keeps replying that screens still look different. Sign off?",
632+
"expected_output": "No -- a 'matches' from a screenshot glance is an assertion, not verification, and repeated correction means the verification METHOD is broken, not that the reviewer needs to point at more examples. Build a mechanical differ before further pixel-matching and gate every 'matches' claim on it: it drives both reference and target per screen and emits a side-by-side + pixel-diff image plus a structured mismatch list (nav/tab labels present or absent each side, header strings, bounding-box deltas) -- the artifact shown is the diff image, never a sentence. Read the reference at its highest fidelity: diff against an existing running build of the design if one is in the repo, else read its source element-by-element; a screenshot of the design is last-resort. Report only what was actually inspected on the target ('the nav now reads Overview, Pipeline, Settings -- I looked at it'), never a blanket 'it matches'; 'not yet verified' beats a false positive. Done = the differ reports zero structural mismatches and a pixel delta under the agreed threshold for every screen, diff images attached. (product-ux-quality.md.)",
633+
"expectations": [
634+
"Rejects a 'matches / pixel-1:1' claim resting on a screenshot glance or any proxy",
635+
"Requires building a mechanical differ and gating every 'matches' claim on its diff artifact",
636+
"Treats repeated stakeholder correction as a broken verification method to change, not more examples to request",
637+
"Reads the reference at highest fidelity (running build > source > screenshot), not a lossy picture"
638+
]
639+
},
640+
{
641+
"id": "match-chrome-never-copy-mock-sample-data",
642+
"prompt": "Our app's metric counts differ from the approved design prototype's (its columns show different tallies and denominators). Should we reconcile our numbers to match the prototype so it's pixel-identical?",
643+
"expected_output": "No -- match the chrome, never the data. Chrome (layout, colour, geometry, tab set, headers) must match; data (values, counts, denominators) must stay real. A prototype fills every number with plausible SAMPLE values to look complete, and copying one into the real product is fabrication (principle 3) -- a Blocker-class data-integrity defect that surfaces weeks later when someone trusts a value lifted from an illustration. Read the prototype's own disclaimer first (mocks routinely mark numbers 'sample / illustrative until the backend is wired') -- that label is the boundary. The parity differ therefore diffs structure and style, not text values, or it flags real data as a mismatch and tempts the copy. Every number in the matched product must trace to a real computation or an honest empty state. (migration-parity.md.)",
644+
"expectations": [
645+
"Refuses to change a real computed value to a mock's sample value",
646+
"Frames copying a mock's number into the product as fabrication / a data-integrity defect, not a styling fix",
647+
"Reads the prototype's own sample/illustrative disclaimer as the chrome-vs-data boundary",
648+
"Keeps chrome matching while every product number traces to a real computation or honest empty state"
649+
]
650+
},
651+
{
652+
"id": "structural-divergence-is-not-close-to-parity",
653+
"prompt": "The board I built has columns [Unclassified, Manual, Planned, In progress]; the design's are [Up next, In progress, In review, Live]. I'd call it close to 1:1, just needs a little polish. Fair?",
654+
"expected_output": "Not close -- that is a category error. A different column / tab model (or a flat list where the design groups by team, or a different page composition) is a STRUCTURAL divergence, not a cosmetic one: it is a different screen, a rebuild, not a polish pass. Classify every difference as structural (components, grouping, column/tab model, composition) vs cosmetic (colour, radius, spacing), establish structural parity FIRST, and only then pursue cosmetic. Never characterise a structural divergence as 'close', 'mostly there', or '1:1' -- say plainly that the structure differs and size it as a rebuild. (product-ux-quality.md.)",
655+
"expectations": [
656+
"Rejects calling a structural (column/tab-model/grouping) divergence 'close' or '1:1'",
657+
"Classifies the difference as structural vs cosmetic and requires structural parity first",
658+
"Sizes a structural divergence as a rebuild, not a tweak/polish"
659+
]
628660
}
629661
]
630662
}

‎.claude/skills/deep-code-review/references/migration-parity.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,33 @@ in the finding, so a downstream implementer does not read it as a cut order. Bef
9595
recommending any structural change to a real surface from a mockup, confirm the
9696
difference is **treatment** (reproducible on **equal** data), not volume.
9797

98+
## Match the chrome, never the mock's data — copying a sample value is fabrication
99+
100+
Separate **chrome** (layout, colour, geometry, tab set, headers, control
101+
affordances — **must match**) from **data** (values, counts, denominators, series —
102+
**must stay real**). A mock is built to *look* complete, so it fills every number
103+
with plausible sample values; those are the one thing that must **not** cross into
104+
the product. **Copying a mock's number into the real product is fabrication**
105+
(principle 3) — a Blocker-class data-integrity defect that surfaces weeks later when
106+
someone trusts a value lifted from an illustration, not computed. This is the
107+
**inverse** of the treatment-not-volume smell above: there the mock's *sparse* data
108+
tempts a wrong cut, here its *invented* values tempt a wrong copy — a design mockup
109+
is neither a feature spec nor a data spec.
110+
111+
- **Read the prototype's own disclaimers first.** Mocks routinely label their
112+
sample numbers ("values marked *sample* are illustrative until the backend is
113+
wired"); that label is the boundary between chrome-to-match and data-to-ignore.
114+
- **Brief the chrome-vs-data split into every parallel worker.** A lane without the
115+
caveat will "helpfully" reconcile the numbers and inject fabricated data, invisible
116+
to the coordinator until it ships (`agentic-delivery`).
117+
- **This is why the parity differ ignores text values entirely** — the differ's
118+
rule follows from this one; see the Phase-6 parity-differ gate (which owns the
119+
differ's exact scope) in `product-ux-quality.md`.
120+
121+
**Acceptance:** every number in the matched product traces to a real computation or
122+
an honest empty state; no value present in the product originates from the design
123+
mock.
124+
98125
## Flow-cost — navigation cost, scroll burden, and cognitive load are first-class
99126

100127
Structural and pixel parity are necessary but not sufficient: a UI can match the
@@ -163,6 +190,13 @@ a separate move: `product-ux-quality.md`, *Match a named standard*.)
163190

164191
- A parity claim ("matches the reference") backed only by a structural audit, a
165192
green suite, or seed-data screenshots — with no surface-by-surface real-data pass.
193+
- A **"matches"** claim on a parity task with **no mechanical differ** — no diff
194+
image or structured mismatch list attached, only an assertion.
195+
- A **structural** divergence (different columns / grouping / composition)
196+
characterised as **"close" / "1:1" / "mostly there"** — a category error; a
197+
different structure is a different screen.
198+
- A number in the matched product **copied from the design mock's *sample* value** —
199+
present in the product but tracing to the mock, not a real computation.
166200
- A recommendation to **drop / remove / replace** a surface or its content to match
167201
a **prototype / mockup** reference (real data → progressive disclosure, not
168202
deletion).

‎.claude/skills/deep-code-review/references/product-ux-quality.md‎

Lines changed: 69 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,16 @@ surface it, don't impose it*).
6161
arrows moved). Re-tuning after a second identical rejection is the failure this
6262
rule names — the design-half form of principle 9 (*root-cause, not symptom*):
6363
after the same failure twice, change the approach, do not repeat the fix.
64+
- **The same move for a *verification* claim: repeated correction means your
65+
method is broken, not their patience.** If a stakeholder repeatedly corrects your
66+
"it matches / it's the same," that is evidence your **verification method** is
67+
wrong — not a cue to ask them for more examples. Change the method: build the
68+
comparator (the **parity differ**, Phase-6 *Enforcing gate* below) and show its
69+
diff, rather than outsourcing your verification back to the person reviewing you.
70+
Report only what you actually inspected on the target ("the nav now reads A · B ·
71+
C, I looked at it"), never a blanket "it matches"; an honest "not yet verified"
72+
beats a false positive (principle 9 again — after the second false "matches",
73+
change the instrument, do not re-assert).
6474
- **Name the structural flaw in one line**, then research how **two or three
6575
comparable products** (named, per *Match a named standard* below) solve the same
6676
problem — the muscle memory the new direction should borrow.
@@ -323,6 +333,7 @@ confidence number published as precision (confidence tier).
323333
- [ ] Verified live in the running product, in more than the happy-path state — **including the default state a user lands on** (signed-out / no-role / default route / local default), not only a mock or a hand-picked persona view?
324334
- [ ] Any "matches / exact / parity" claim checked against the **default served state** as the canonical surface — and if it rests on a non-default surface, does it **name** that surface and say the default was not checked?
325335
- [ ] "Looks the same" backed by a **rendered-appearance** diff of the default state vs the reference (screenshot / computed styles), **not** section-presence, DOM order, a passing test, or loaded data — and stating **which axis** (structure / styling / content / data) the evidence covers, without "fixing" data to answer a styling complaint?
336+
- [ ] Parity task: differences classified **structural vs cosmetic** (structural parity first; a structural divergence **never** called "close / 1:1"); every "matches" claim gated on a **mechanical differ** (diff image + structured mismatch list attached, not an assertion); reference read at its **highest fidelity** (running build > source > screenshot); and **no mock sample value copied** into the product?
326337
- [ ] Did **not reconfigure the default** (persona / seed / flag / env) and then claim "verified on the default" — checked the pre-existing default and disclosed any change to it?
327338
- [ ] Every styling / placement delta enumerated in **one** side-by-side pass and fixed against that inventory — not piecemeal-fix-then-redeclare-done?
328339
- [ ] Told "not the same" → **asked which axis** before acting (after one wrong guess, asked not guessed), and compared the **reference itself** at the element × breakpoint × theme, not from memory?
@@ -352,15 +363,27 @@ is that a parity ✅ resting on a **non-default surface** is not green.
352363
## "Looks the same" is about rendered appearance — four axes, and a structural check is not a visual one
353364

354365
"Make X look like reference Y" is a task that frequently earns a false ✅. These
355-
rules sit **on top of** the default-state rule above (never restating it); each
356-
names a distinct evasion that passes a default-state check yet still ships a UI
357-
that does not look like Y.
366+
rules sit **on top of** the default-state rule above (never restating it); each is
367+
a distinct fidelity rule, or names an evasion that passes a default-state check yet
368+
still ships a UI that does not look like Y.
369+
370+
**Read the reference at its highest available fidelity — this is the *reference*
371+
side, not your output's.** The reference exists in three forms; prefer the highest
372+
present: a **running build** you launch and diff against > the design **source**
373+
(HTML/CSS, which states the column model, tokens, and spacing exactly) you read
374+
property-by-property > a **screenshot** (a lossy picture — last-resort sanity check
375+
only). Never reverse-engineer the source when a running build of the design
376+
already exists in the repo, and never eyeball a picture when the source or build
377+
states the spec precisely. This governs how you read **Y**; it does not soften the
378+
rule below that *your implementation's* evidence must be the **render**, not the
379+
DOM — opposite sides of the comparison.
358380

359381
**Four axes — name which one a claim covers; never conflate them.** A UI compares
360382
on four independent axes:
361-
- **structure** — which sections exist, in what order, nesting / DOM;
362-
- **styling** — font size / weight, colour, spacing, radius, shadow; chrome
363-
present or absent; each affordance's presence and **glyph** (a star, a caret, a
383+
- **structure** — which sections / components / chrome / affordances are
384+
**present** (vs absent), in what order, grouping, nesting / DOM;
385+
- **styling** — the rendered *look* of what is present: font size / weight,
386+
colour, spacing, radius, shadow; each affordance's **glyph** (a star, a caret, a
364387
control); overall layout dimensions;
365388
- **content** — the words / copy;
366389
- **data** — the numbers / rows / entities.
@@ -372,6 +395,21 @@ it is **not** evidence of styling parity and must never be reported as "matches"
372395
answer a **styling** complaint: that changes an axis the user did not raise and
373396
leaves the one they did.
374397

398+
**Classify every diff structural vs cosmetic — and get structural parity first.**
399+
Structural = different components, a different grouping / column / tab model, a
400+
different page composition — the **structure** axis above (presence, grouping,
401+
composition); cosmetic = colour, radius, spacing, glyph — the **styling** axis.
402+
(Same two axes, renamed for the parity decision: presence/composition is
403+
structural; the rendered look of what is present is cosmetic.) Establish
404+
structural parity first (same components, same grouping, same composition), then
405+
pursue cosmetic. **Never characterise a structural divergence as "close", "mostly
406+
there", or "1:1"** 🚩: a board whose columns are `[Unclassified, Manual, Planned,
407+
In progress]` when the design's are `[Up next, In progress, In review, Live]`, or a
408+
flat filtered list where the design groups by team, is not "nearly there" — it is a
409+
**different screen**, a rebuild, and calling it close is a category error that
410+
destroys stakeholder trust. If the structure differs, say so plainly and size it as
411+
a rebuild, not a tweak.
412+
375413
**A structural / proxy check is not visual evidence.** A section-presence check, an
376414
"element-by-element" DOM / heading diff, a passing test, or loaded data are all
377415
**proxies** for rendered appearance, not the appearance itself (`report-format.md`,
@@ -438,8 +476,9 @@ ships a UI, pair this reference with a UX-evidence gate — held to the skill's
438476
gate discipline: **a gate must tell "could not check" from "found a problem,"
439477
fail *open* on the former, and never be stricter than the standard**
440478
(`frontend-a11y.md`, the `innerText` and disabled-contrast traps; SKILL.md
441-
Phase 1, gate-vs-standard). Three gates, in descending confidence of what they
442-
can prove:
479+
Phase 1, gate-vs-standard). Three gates for any UI change, in descending
480+
confidence of what they can prove — plus a fourth that fires only on a parity
481+
task:
443482

444483
1. **Screens-changed evidence (proves a look happened).** On any diff that can
445484
change a rendered page, require a screenshot of each affected route at a narrow
@@ -460,5 +499,25 @@ can prove:
460499
`unverified`, not as clean. Model: a renderer-tolerant ratchet — a pinned
461500
exception is *allowed*, never *required* to exhibit.
462501

463-
Ship all three **idempotent and additive**, per Phase 6 — detect-and-stop if
464-
present, add only what is missing, defer to an existing style guide.
502+
4. **Parity differ (parity tasks only — proves *equivalence*, not just that a human
503+
looked).** For a "make X match reference Y" task, build a mechanical differ
504+
**before** any pixel-matching and gate every "matches" claim on it. The differ
505+
drives both the reference and the target for each screen and emits (a) a
506+
side-by-side + pixel-diff **image** and (b) a **structured** mismatch list — which
507+
nav / tab labels are present or absent on each side, the header strings, and
508+
bounding-box geometry deltas for key elements. **The artifact shown to a reviewer
509+
is the diff image, never a sentence.** Load a no-routing prototype **once and
510+
click-navigate** its in-page tabs (it has no per-screen URL to fetch), and diff
511+
against an existing **running build** of the design if one is in the repo rather
512+
than reverse-engineering its source (reference-fidelity order, "Looks the same"
513+
above). It diffs **chrome / structure / styling, not text values** — diffing the
514+
numbers would flag real data as a mismatch and tempt the fix that fabricates
515+
(`migration-parity.md`). What it **cannot** prove: an intentional improvement from
516+
a regression, and its pixel threshold is **agreed, not derived** — a human still
517+
owns the ship call. *Done* on a parity task = the differ reports zero structural
518+
mismatches and a pixel delta under the agreed threshold for every screen in the
519+
correspondence table, with those diff images attached — never an assertion.
520+
521+
Ship these **idempotent and additive**, per Phase 6 — detect-and-stop if
522+
present, add only what is missing, defer to an existing style guide (the parity
523+
differ only when the task is a parity task).

‎.claude/skills/idea-critic/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: >-
99
license: MIT
1010
metadata:
1111
author: deep-code-review contributors
12-
version: "1.76.0"
12+
version: "1.77.0"
1313
---
1414

1515
# Idea critic

‎.claude/skills/idea-critic/VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.76.0
1+
1.77.0

0 commit comments

Comments
 (0)