You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a708c36
Browse filesBrowse the repository at this point in the historyBrowse files
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>
Copy file name to clipboardExpand all lines: .claude-plugin/plugin.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
"name": "deep-code-review",
3
3
"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.",
Copy file name to clipboardExpand all lines: .claude/skills/deep-code-review/evals/evals.json
+32Lines changed: 32 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -625,6 +625,38 @@
625
625
"Requires distinguishing no-data-collected/covered from collected-and-genuinely-none",
626
626
"Requires the empty state to name coverage (was the source actually probed), not imply a false all-clear"
627
627
]
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"
"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"
Copy file name to clipboardExpand all lines: .claude/skills/deep-code-review/references/product-ux-quality.md
+69-10Lines changed: 69 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,6 +61,16 @@ surface it, don't impose it*).
61
61
arrows moved). Re-tuning after a second identical rejection is the failure this
62
62
rule names — the design-half form of principle 9 (*root-cause, not symptom*):
63
63
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).
64
74
-**Name the structural flaw in one line**, then research how **two or three
65
75
comparable products** (named, per *Match a named standard* below) solve the same
66
76
problem — the muscle memory the new direction should borrow.
@@ -323,6 +333,7 @@ confidence number published as precision (confidence tier).
323
333
-[ ] 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?
324
334
-[ ] 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?
325
335
-[ ] "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?
326
337
-[ ] 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?
327
338
-[ ] Every styling / placement delta enumerated in **one** side-by-side pass and fixed against that inventory — not piecemeal-fix-then-redeclare-done?
328
339
-[ ] 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.
352
363
## "Looks the same" is about rendered appearance — four axes, and a structural check is not a visual one
353
364
354
365
"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.
358
380
359
381
**Four axes — name which one a claim covers; never conflate them.** A UI compares
360
382
on four independent axes:
361
-
-**structure** — which sections exist, in what order, nesting / DOM;
0 commit comments