Skip to content

feat(report): /parity:report — stakeholder deck + one-pager kit - #320

Merged
JonasJesus42 merged 1 commit into
mainfrom
feat/stakeholder-report
Aug 27, 2026
Merged

feat(report): /parity:report — stakeholder deck + one-pager kit#320
JonasJesus42 merged 1 commit into
mainfrom
feat/stakeholder-report

Conversation

@JonasJesus42

@JonasJesus42 JonasJesus42 commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

What

Packages the report-building pattern used on the Electrolux Ecuador POC into the
plugin, so the next migration does not rediscover it.

New command /parity:report (--shape deck|onepager, --audience team|exec,
--before/--after) and skill stakeholder-report with a runnable asset kit.

Plugin layer only — no packages/parity/ change, so no CLI surface to document.

The deck shell carries a real fix

assets/deck.js is the lateral-scroll shell. The naive version — a wheel handler
that only asks "can any ancestor still scroll in this direction?" — pages the
deck the instant an inner scroller bottoms out, and the trackpad inertia from
that same gesture is what fires it. Reaching the end of a table flipped the
slide, which reads as a design decision rather than a bug.

Fix: a second check (inScroller — is the pointer inside a scrollable subtree at
all, edge or not) plus a ~350ms rearm latch. Inertia keeps the latch warm; after
a real pause the next scroll pages. The delta accumulator is also reset whenever
the scroll is consumed internally, otherwise the deltas add up and the page turns
by itself seconds later.

The evidence rules are the point

These are what keep a client-facing report defensible, and each one comes from
something that actually went wrong:

  • Verify every tool claim. Parity reported ?page=2 and ?page=3 as HTTP
    404 — it had invented the route /383; the real collection returns 200.
  • Never measure a local candidate. 66 of 187 findings came from
    GTM_CONTAINER_ID being unset: the placeholder container made every analytics
    beacon and third-party script look divergent, and dropped the console module
    from 100 to 78. Measure the deployed candidate.
  • Triage into defect / content difference / false positive, and keep the last
    two out of the headline count. A "4 critical" tile where 3 are content
    differences collapses under one question.
  • Label what is not measured yet. A pending after-number presented as a
    result is the fastest way to lose the room.
  • Completeness estimates need a declared rubric — publish the weights, and
    call it a judgement, not a measurement.

Editorial rules

Cut flourish, cut repetition including structural repetition, and do not put a
number on something the number understates — a PR count measures how work was
packaged, not how much work happened. If the honest number reads small, describe
the thing without quantifying it, and never substitute a larger one.

Files

Path What
commands/report.md the command; opens with the three questions that decide the report
skills/stakeholder-report/SKILL.md evidence + editorial rules, page components, checklist
assets/deck.css design kit + the components added since (.flow, .pair, .callout)
assets/deck.js deck shell with the scroll latch
assets/deck-template.html runnable 3-page skeleton
assets/capture.md the capture scripts that worked, and why the obvious ones failed
assets/build.py generator scaffold with self-checks

README.md, hooks/session-start.md and SKILLS-AUDIT.md updated to list it.

Verification

  • Smoke test: assembled a real deck from template + css + js — 3 pages, 3 dots,
    balanced tags, zero template classes without a CSS rule.
  • node --check assets/deck.js and ast.parse(assets/build.py) clean.
  • Code fences balanced in both markdown files; SKILL.md front matter valid.
  • Caught while testing: the template's header comment contained literal <style>
    and <script>, which tripped the tag-balance checker. Reworded, and
    style/script removed from build.py's check — their content is arbitrary
    text, not nestable containers.

No example generator from the client project is vendored: it carries customer
data, and build.py already carries the pattern without the case.


Summary by cubic

Adds the /parity:report command and stakeholder-report skill so future migrations can build stakeholder decks and one-pagers without rediscovering the pattern. The deck shell also fixes a scroll bug where trackpad inertia flipped the slide right after an inner table bottomed out.

New Features

  • /parity:report takes --shape deck|onepager, --audience team|exec, and --before/--after git refs.
  • Skill ships a design kit, runnable template, generator scaffold with self-checks, and a capture recipe for before/after shots.
  • Evidence rules require verifying every tool claim, measuring the deployed candidate rather than localhost, and splitting findings into defect / content difference / false positive.

Bug Fixes

  • Deck shell now swallows wheel events while trackpad inertia is still running after an inner scroller reaches its edge, via an inScroller check and a ~350 ms rearm latch.
  • The delta accumulator resets whenever scroll is consumed internally, so the page cannot turn by itself seconds later.

Written for commit 08a4636. Summary will update on new commits.

Review in cubic

Packages the report-building pattern we used on the Electrolux Ecuador POC into
the plugin, so the next migration does not rediscover it.

New command `/parity:report` and skill `stakeholder-report`, carrying:

- The design kit (`deck.css`) and the lateral-scroll shell (`deck.js`). The
  shell fixes a bug the naive version has: a wheel handler that only asks "can
  any ancestor still scroll?" pages the deck the instant an inner scroller
  bottoms out, and trackpad inertia from that same gesture is what fires it.
  Reaching the end of a table flipped the slide. Fixed with a second check
  (`inScroller`, edge or not) plus a ~350ms rearm latch, and by resetting the
  delta accumulator when the scroll is consumed internally.

- Evidence rules, which are the reason the report holds up. Verify every tool
  claim before it ships: on the real run, parity reported a pagination 404 on a
  route it had invented. Never measure a local candidate: 66 of 187 findings came
  from GTM_CONTAINER_ID being unset. Triage findings into defect / content
  difference / false positive, and keep the last two out of the headline count.

- Editorial rules: cut flourish, cut repetition including structural repetition,
  and do not put a number on something the number understates — a PR count
  measures packaging, not work. Never substitute a larger one.

- Capture recipe with the scripts that worked (`capture.md`): worktree at a tag
  for the "before", Cypress for same-origin, headless Chrome for the cross-origin
  checkout hop where Cypress dies, and the compression pass that takes eight
  captures from 40MB to under 1MB.

- A generator scaffold (`build.py`) with self-checks, because a slice edit in a
  generator silently drops a whole page.
@JonasJesus42
JonasJesus42 merged commit f24fbb1 into main Aug 27, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant