groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-designer/references/accessibility.md

@@ -0,0 +1,33 @@
+# Accessibility
+
+When you advise on accessibility, treat it as a design-time property, not a remediation phase — the constraints it imposes (clear hierarchy, visible focus, semantic structure, predictable navigation) produce better software for every user. WCAG 2.2 AA is the floor for every surface; a feature that fails a keyboard or screen-reader user is not finished.
+
+## WCAG 2.2 AA is the floor, not the ceiling
+
+Conform to WCAG 2.2 AA for every page, component, and release, aiming higher on critical journeys where the cost is bearable. Falling below AA is a bug, not a trade-off. The 2.2 additions that bite at design time are concrete: interactive targets at least 24×24px (or spaced to compensate), a focused element never fully hidden behind sticky chrome, any drag operation with a single-pointer alternative, and authentication that allows password managers and paste rather than a memory test.
+
+## Keyboard first; manage focus
+
+Every interactive element is reachable and usable by keyboard, tab order is logical, focus is always visible, and there are no keyboard traps. The design test is simple: can a user who cannot use a pointer complete every journey? Never remove the focus outline without a replacement meeting 3:1 contrast; use `:focus-visible` to show it for keyboard and not mouse. On client-side route changes, move focus to the new view and announce it, because a silent route change is the dominant single-page-app accessibility bug. In a modal, move focus in, trap it while open, close on Escape, and return focus to the trigger.
+
+## Semantic HTML first; ARIA only to augment
+
+Reach for native elements — `<button>`, `<a href>`, `<input>`/`<label>`, `<nav>`, `<dialog>` — before any ARIA, because native elements carry role, name, state, keyboard behaviour, and focus for free, and bad ARIA measurably *adds* errors. ARIA augments (`aria-expanded`, `aria-current`, live regions); it never adds behaviour and never overrides a visible name. Give the screen reader structure: one `<main>` and landmark regions, a heading outline with no skipped levels, an accessible name on every control. Announce dynamic updates through an `aria-live` region that already exists in the DOM at load — but sparingly, because over-announcement makes screen readers ignore what matters.
+
+## Colour is never the only signal; motion is optional
+
+Any meaning carried by colour is redundantly encoded with text, icon, shape, or position, because colour-only signalling excludes colourblind users. Text meets 4.5:1 (3:1 for large and for non-text UI). Honour `prefers-reduced-motion`: disable parallax and large transitions, keep essential feedback — unrequested motion is an accessibility failure for vestibular users, not decoration — and honour `prefers-contrast` and `prefers-color-scheme`.
+
+## Testing is multi-layered
+
+Automated checks (axe, Lighthouse) run in CI as a non-negotiable gate, but they catch only ~30–40% of criteria, so they are the floor: keyboard-walk every new journey, run a screen-reader pass on key flows, and spot-check contrast, 200% zoom, and reduced motion. Automation finds the mechanical failures; humans find the semantic ones — whether alt text is meaningful, whether focus order makes sense, whether a custom widget actually works with assistive technology.
+
+## Antipatterns to catch
+
+- **Placeholder as label.** It disappears on input; the field's purpose is then gone.
+- **`<div>` as button.** Invisible to keyboard, screen reader, and user agent — use `<button>`.
+- **Focus removal for aesthetics.** `outline: none` with no replacement breaks keyboard navigation.
+- **Colour-only state.** Red/green error and success with no text or icon.
+- **Modals without focus management.** Focus left behind, the page read underneath, no return on close.
+- **"We'll add a11y in v2."** v2 will not have it either; build it in.
+- **"axe passes, so it's accessible."** False confidence over the untested majority of criteria.

package/src/hidden-skills/groundwork-designer/references/ai-native-design.md

@@ -0,0 +1,37 @@
+# AI-Native Design
+
+When you advise on a probabilistic or generative feature, design for the distribution of outputs, not a single answer. The core failure is a probabilistic engine wrapped in a deterministic interface that presents a guess as truth; the discipline is making the uncertainty legible and controllable so the user collaborates with the system instead of being surprised by it.
+
+## Design the outcome envelope, not one happy path
+
+Design for the range of what the feature might produce, because the exact rendered output is no longer under your control. Vary the treatment by likelihood of intent — more framing where confidence is low, less friction where high — prefer ranges and windows over false-precise points, and plan explicit fallback states for degrading confidence. Because ideation is cheap with these systems, presenting multiple candidates is often the right default.
+
+## Latency is a design material
+
+Optimise time-to-first-token and stream immediately, because streaming removes the wait-for-completion delay even though it does not speed the model, and perceived speed is the metric. Show structured progress past ~1s, let the user act on partial output, and parse streaming content incrementally rather than re-rendering the whole response per chunk. An unindicated wait past ~10s collapses satisfaction.
+
+## Communicate confidence without false precision
+
+Prefer calibrated categorical confidence (high / medium / low) and first-person hedging at the point of the claim, reserving numeric scores for high-stakes domains with comparable predictions, because a single definitive score drives over-reliance then trust collapse and a spurious percentage implies precision the model lacks. Do not amplify the model's default overconfidence.
+
+## Ground claims; design the wrong answer first
+
+Where the feature makes factual claims, assemble citations during generation from the retrieval context, at the passage level, and surface missing or broken sources explicitly, because a citation creates a halo that lowers vigilance so a gap must be shown. Treat incorrect output as the norm and design that flow before the happy path: sandbox unpredictable output to a region so it cannot break the deterministic UI, mark doubt in context rather than in a global disclaimer that habituates into noise, and make correction cheap with feedback routed back. Never feed unverified output straight into an irreversible action.
+
+## Keep the human on the dial
+
+Autonomy is a slider the user controls. Gate on reversibility crossed with severity — irreversible high-severity actions (send, charge, delete, deploy) need pre-approval; reversible high-severity gets oversight with a rollback window; reversible low-severity runs autonomously — and show the agent's reasoning at the gate, because an action the user cannot preview feels like a surprise they did not consent to. Gating everything is its own failure: alert fatigue turns approval into rubber-stamping. Make regeneration and steering first-class and non-destructive, never silently discarding prior outputs.
+
+## Chat is one tool, not the universal interface
+
+Chat became the default because it was easiest to ship, not because it suits most tasks: a bare text box has no affordances, hides the system's capabilities, and forces constant switching between instructing and evaluating. Most AI features are better as embedded, affordance-rich tools — highlight-to-rephrase, context-menu actions, ambient agents — with conversation reserved for open-ended dialogue and paired with a directly manipulable canvas. Design for control and legibility — copilots, not captains — over "magic" autonomy.
+
+## Antipatterns to catch
+
+- **A guess as truth.** A single confident answer with no confidence signal, sources, or cheap correction.
+- **The blocking wait.** Holding the full response instead of streaming with progress.
+- **False precision.** Spurious percentage confidence, amplifying the model's overconfidence.
+- **Retrofitted citations.** Document-level references grafted on, useless for verifying a claim.
+- **The global disclaimer.** One "AI can make mistakes" line replacing in-context doubt.
+- **Approve-everything or approve-nothing.** Rubber-stamp fatigue, or auto-running irreversible actions.
+- **Chat as the answer to everything.** A chat widget where an embedded tool would serve better.

package/src/hidden-skills/groundwork-designer/references/design-review.md

@@ -0,0 +1,29 @@
+# Design Review — Judging the Implemented UI
+
+When you judge a delivered interface, judge it in the running software, against the intent it was meant to express and the references it drew from — not against the comp, and not by a recited checklist. This is where the discipline earns its keep: the design system is only delivered if the rendered product reaches it, and someone has to look and say whether it did.
+
+## Judge in the material, against a named bar
+
+Look at the actual rendered states, not the design file, because the screen is the only place the design exists for the user. A review needs two things to be more than opinion: the stated intent (what this was meant to feel like and do) and the named references the work admired. Craft is judged against a bar, so an unnamed bar cannot be met or checked — pull the references at review time (the market leaders the work cited have abundant public design imagery) and ask the defensible question: is this as considered as the thing we said we admired?
+
+## Reason over dimensions, do not recite a checklist
+
+Hold the implemented screen against the dimensions that carry quality, and reason about each rather than ticking it: did the intent survive translation (do the rendered colour, type, space, and motion match the specified tokens, or did the build drift to framework defaults); rendering integrity (does each state render free of overflow, clipping, misalignment, broken assets); layout and alignment against the spatial system; perceptual craft (perceptual colour, modelled depth, typographic rigour, purposeful motion — or the generic signatures: a flat shadow, one font weight, a default gradient, a single linear ease); and state coverage (are empty, loading, partial, error, and success actually designed, or only the populated path). A fixed checklist both narrows what you look for and reads identically every session; describe the dimensions and let the review surface what is wrong.
+
+## Hold a real quality bar
+
+A finding is only useful if it is specific enough to act on and calibrated to the bar. The difference is concrete: a thin "the spacing feels off" is noise beside a deep "the card grid uses a 12px gutter where the 8-point rhythm calls for 16px, so the density reads cramped against the Linear-class restraint the references set." Name the dimension, the observed value, the specified or admired target, and why the gap matters. Separate what violates the design system (a defect — wrong token, missing state) from what merely falls short of the craft bar (a lift — technically conformant but generic).
+
+## Distinguish durable craft from fashion
+
+Judge against durable craft — perceptual colour, motion with purpose, modelled depth, typographic rigour — not a passing visual fashion. Matching a leader means matching its underlying rigour and restraint, never copying its signature look, because the signature dates and the rigour does not. A review that asks the product to mimic a trend has mistaken the surface for the craft.
+
+## Antipatterns to catch
+
+- **Reviewing the comp.** Judging the design file instead of the rendered, stateful product.
+- **The recited checklist.** A fixed list that narrows attention and repeats verbatim every session.
+- **The unnamed bar.** "Make it nicer" with no intent and no reference to judge against.
+- **Thin findings.** "Spacing feels off" with no value, target, or reason — unactionable.
+- **Defect and lift conflated.** Treating a system violation and a craft shortfall as the same severity.
+- **Mimicry as the goal.** Asking for a leader's signature look instead of its rigour.
+- **Stopping at the happy path.** Reviewing the populated state and never opening empty, loading, or error.

package/src/hidden-skills/groundwork-designer/references/design-systems-and-tokens.md

@@ -0,0 +1,33 @@
+# Design Systems & Tokens
+
+When you advise on the design system, treat it as the durable contract between design and engineering: semantic tokens as its wire format, components as its typed interfaces. The decisions that determine whether it holds are tiering tokens correctly and wiring the system to production so it is implemented, not decorated.
+
+## Tokens are tiered; primitives are never consumed directly
+
+A token system has three tiers. **Primitives** are context-free raw values — colour ramps, the spacing and radius scales, durations — with no usage intent. **Semantic** tokens alias primitives by role (`color.background.default`, `border.hairline`) and are the layer components bind to and themes remap. **Component** tokens are scoped overrides referencing the semantic tier, an escape hatch promoted only on real repeated need. A component never reads a primitive directly, because wiring it to `blue.500` makes theming a rewrite; cap indirection at roughly two hops. Name by intent, never by value — `color.feedback.error`, not `red-600` — because a value-named token lies the moment its value changes, and intent names are what make the system legible to both a human and an AI agent.
+
+## Theme at the semantic tier; model axes as orthogonal overrides
+
+Theming is a mapping swap at the semantic layer — the name stays, the primitive it points to changes per mode — so components and primitives stay theme-agnostic. Model every dimension (light/dark, contrast, brand, density) as an independent override set resolved by order, because orthogonal axes *add* while names that encode a dimension *multiply*, and only the additive model survives a fifth axis. Never precompute the full permutation matrix; author high-contrast or colourblind themes as thin diffs, not duplicate sets.
+
+## Components are contracts
+
+A component's public surface — props, slots, states, accessibility semantics — is designed like a typed signature and versioned like one: additions minor, renames and removals major with a deprecation window and codemod. Variant, state, size, and slot are orthogonal axes; each enumerable axis is one enum, not a pile of booleans, because an enum makes illegal states unrepresentable where boolean soup multiplies the test matrix. The same concept carries the same prop name everywhere — that consistency is what makes the system learnable. Prefer composition (compound components sharing state) over configuration, and separate a headless, ARIA-conformant behaviour core from visual decisions (semantic tokens) from product-specific recipes.
+
+## The system is truth in code, wired to production
+
+Tokens are the source of truth as version-controlled data, compiled into the styles the app actually serves; the design tool consumes this, it does not originate it. The system is *implemented, not decorative*, and the test is mechanical: change one semantic token and the running product moves — if it does not, it is a museum piece. Run it as a product with a central core team, add federated contribution gradually, and measure **adoption** (the share of production UI on the system), not contribution count, because most components built across teams do not belong in the core. Enforce the contract in CI: no raw hex or off-scale values, deprecated-token detection, visual regression.
+
+## Make the system machine-legible
+
+Author the system so an AI agent builds on it: intent-named tokens carrying usage descriptions and relationships, components with documented, discoverable APIs. A grounded agent reuses the system; an ungrounded one invents ad-hoc UI, and one reading value-named, undescribed tokens grabs the wrong one. Machine-legibility is an extension of naming-by-intent — but tokens are plumbing; the craft and architecture above them are where the value lives.
+
+## Antipatterns to catch
+
+- **Primitives in components.** `button { color: blue.500 }`, turning a theme change into a refactor.
+- **Value-named semantics.** `neutral-80` used as if it meant something.
+- **Theming the primitive layer.** Collapsing the indirection that makes theming possible.
+- **Dimension-in-the-name.** Encoding mode/brand/density into names, multiplying the matrix.
+- **The boolean trap.** `isPrimary`/`isLarge` where one enum belongs, permitting illegal states.
+- **The decorative system.** A design-tool library reproduced by eye, with a parallel hand-kept token set.
+- **Adoption by contribution count.** Measuring components added, not production on the system; promoting every snowflake.

package/src/hidden-skills/groundwork-designer/references/interaction-and-motion.md

@@ -0,0 +1,37 @@
+# Interaction & Motion
+
+When you advise on interaction, the interface has two jobs: communicate what it can do, and communicate what just happened. The decisions that matter most are the ones an engineering-led build skips — the states the user actually lives in, and motion that earns its place.
+
+## Affordance is signalled; feedback is immediate
+
+Every actionable element carries a perceptible signifier (shape, weight, underline, cursor, label), because an affordance the user cannot perceive does not exist for them; a non-interactive element avoids signifiers that imply action. Every action gets a response within ~100ms, proportional and located at its point, because the user builds a mental model only from feedback they can see.
+
+## Design every state, not the happy path
+
+Every surface that loads or mutates data is designed for six states: **empty** (first-use teaches and offers one action — distinguish first-use from cleared from no-results), **loading** (skeleton matching final layout for content, spinner for short waits, determinate progress past ~1s), **partial** (render what you have, stream the rest), **error** (in-context, specific, recoverable, input preserved), **success** (confirm clearly — the remembered ending), and **populated** (which must survive real data extremes — long strings, huge counts, missing fields). Designing only the populated state is the most common production failure, and the skipped states are where trust is won or lost.
+
+## Motion serves a function or is cut
+
+Every animation justifies itself against feedback, continuity, focus, or perceived performance, and motion that serves none is removed. High-frequency and keyboard-initiated actions get no animation, because an interface used hundreds of times a day feels fast precisely when it does not animate.
+
+## Motion runs on physics and stays out of the way
+
+The default is `ease-out`, ~200ms, animating only `transform` and `opacity` — compositor-only properties that hold frame rate, where `width`/`margin`/`box-shadow` drop frames. `ease-in` is never used on UI (it feels sluggish); springs tuned by duration and a subtle bounce (≈0.1–0.3) are preferred for anything grabbable or interruptible, because a spring keeps velocity when interrupted while a tween restarts from zero. Elements enter from `scale(0.95)`, never `scale(0)`. A related sequence enters with a short stagger (≈20–50ms) reading as one gesture; use the View Transitions API for shared-element and page transitions over hand-built FLIP.
+
+## Speed is designed
+
+Budget feedback to the perceptual thresholds — under ~100ms feels instant, ~1s holds the flow of thought, ~10s is the limit of attention — and design to them. Make low-risk, high-success mutations optimistic: apply the effect immediately and reconcile in the background, reverting visibly on failure, because acting before the network confirms is what feels fast. Reserve spinners for risky or slow operations; use skeletons only when content-shaped and longer than ~1s, matching the final layout.
+
+## Reduced motion is the safe baseline
+
+Author the muted baseline and layer motion inside `prefers-reduced-motion: no-preference`, so it fails safe for vestibular conditions. Reduce, do not remove — disable triggers (parallax, large translations, scale, spin, autoplay), keep functional feedback (quick fades, focus, state), replace a slide with a cross-fade. Meaning never rides on motion alone; when motion is reduced, state still reads through colour, text, icon, and layout.
+
+## Antipatterns to catch
+
+- **Happy-path-only.** Shipping the populated state, abandoning users in empty, loading, and error.
+- **Mystery-meat UI.** Text, links, and buttons made visually indistinguishable.
+- **`transition: all` and `ease-in`.** Animating layout-triggering properties on a sluggish curve.
+- **Animation on everything.** Decorative motion on high-frequency or keyboard actions.
+- **Unsafe optimism.** Optimistic updates on irreversible or low-success actions.
+- **Frame-display skeletons.** Skeletons not matching the layout, or flashing on sub-300ms loads.
+- **Motion as the only signal.** State conveyed solely by movement, lost when motion is reduced.

package/src/hidden-skills/groundwork-designer/references/layout-and-space.md

@@ -0,0 +1,33 @@
+# Layout & Space
+
+When you advise on layout, treat space as a designed material and let the layout be intrinsic to its content. The two decisions that separate a portable, rhythmic interface from a brittle one are a single tokenised spacing scale and putting responsiveness in the container rather than the viewport.
+
+## Space comes from one scale; relatedness is spacing
+
+Every margin, padding, and gap is a step on one spacing scale, in `rem`, generated from a single base variable so the whole system rescales from one place and honours user font-size. Use a 4px base with 8px as the dominant cadence and a non-linear scale (4, 8, 12, 16, 24, 32, 48, 64, 96), because steps should stay perceptually proportional rather than waste tokens on imperceptible large-end jumps. Spacing communicates structure: related elements sit closer than unrelated ones, so internal spacing is always less than the spacing between groups — equal spacing everywhere erases grouping the user then has to reconstruct.
+
+## Layout is intrinsic: Grid for structure, Flexbox for flow
+
+Let layout size from content — `minmax()`, `min()`, `fr`, `ch`, `auto-fit`/`auto-fill` — rather than forcing fixed columns. Grid handles two dimensions, Flexbox one; matching the tool to the dimensionality makes the alignment hacks disappear. Subgrid aligns content across sibling cards without fixed heights or JavaScript. The responsive-grid default is the RAM pattern *with its guard* — `repeat(auto-fill, minmax(min(100%, 16rem), 1fr))` — because the bare `minmax(16rem, 1fr)` overflows below the floor.
+
+## Responsiveness belongs to the container
+
+A reusable component knows the space its slot gives it, not the viewport. Make every reusable component a container (`container-type: inline-size`) and write its internal breakpoints with `@container`, reserving `@media` for page-level chrome, because that is what makes the same card lay out correctly in a wide column and a narrow sidebar at one viewport width. A `@media` query inside a component couples it to the page and kills portability.
+
+## Type and space scale fluidly; density is an axis
+
+Ship generated fluid scales — type and space as `clamp()` tokens interpolating between a small- and large-viewport anchor — so the system scales smoothly and stays consistent from one declaration; every fluid font-size carries a `rem` term, never pure `vw`. Treat density as an explicit named mode (default and compact) driven by tokenised 4px height deltas plus tighter line-height, not by hand-shrinking components — applied to dense data regions, withheld from focused inputs, never below the accessible touch-target minimum.
+
+## Author in logical properties; place breakpoints by content
+
+Write layout in flow-relative logical properties (`margin-inline`, `padding-block`, `inset-inline-end`, `text-align: start`) by default, because one stylesheet then internationalises to right-to-left and vertical writing for free. Reserve media its space with `aspect-ratio` + `object-fit: cover` to prevent layout shift. Where discrete breakpoints remain, place them in `em` at the widths your *content* breaks, author mobile-first, and design an explicit desktop density target — a single-column mobile layout stretched to a wide screen reads as low-density and untrustworthy.
+
+## Antipatterns to catch
+
+- **Magic-number spacing.** `padding: 7px`, off-scale values that break the rhythm grouping needs.
+- **`@media` inside a component.** Couples it to the page; the container is the right reference.
+- **Faking 2D with Flexbox.** Ragged pseudo-columns where Grid or subgrid would align.
+- **The unguarded RAM pattern.** `minmax(16rem, 1fr)` without `min(100%, …)`, overflowing on narrow screens.
+- **Pure-`vw` fluid type.** A `clamp()` preferred value with no `rem` term, breaking zoom.
+- **Physical properties.** `margin-left`/`text-align: left` landing on the wrong side in RTL.
+- **Stretched mobile layout.** A phone single-column shipped unchanged to desktop.

package/src/hidden-skills/groundwork-designer/references/usability-and-ux.md

@@ -0,0 +1,33 @@
+# Usability & UX
+
+When you advise on usability, the heuristics and UX laws are tools for *making* the decision in front of you, not a checklist to run afterward. The discipline is applying the known fix at design time, when it is free, instead of discovering the problem in a test after the structure has hardened around it.
+
+## Heuristics and laws as decision lenses
+
+Hold the heuristics up as lenses while you design: is status visible, does the language match the user's world, is there a marked exit from every state, is it consistent with what users know elsewhere, are errors prevented before messaged, recognition favoured over recall, both novice and expert served, errors routed to a fix. The UX laws carry direct implications — Fitts: primary actions large and near, destructive small or distant, edges are infinite targets. Hick: reduce and group choices, offer a default. Jakob: meet convention first. Tesler: the product absorbs irreducible complexity, not the user. Postel: accept messy input and normalise it. Peak-End: invest in the peak and the ending. Von Restorff: distinguish the one most important action — if everything is emphasised, nothing is.
+
+## The product absorbs complexity
+
+Make the product bear the load: sensible defaults so the common case needs no decision, values derived rather than asked, the happy path tuned for first use with accelerators layered for experts. Attack *extraneous* cognitive load — clutter, inconsistency, unnecessary choices — because every scrap of attention spent decoding the UI is attention off the task. Reveal complexity progressively: the common 80% first, advanced options one discoverable layer deep. For complex or branching flows, one question per page beats a long wall of fields.
+
+## Forms ask less, validate kindly, never lose work
+
+A form is a single column with labels above the field — fastest to complete, survives translation — never a placeholder standing in for a label, which vanishes on input and fails review and accessibility. Validate on blur and confirm success inline, never erroring mid-keystroke. On failed submit, keep every value, mark each field inline, summarise at the top, and move focus to the first error. Pre-fill what you can infer, cut every field not needed now (each one lowers completion), use the right input type, and accept any reasonable format.
+
+## Prevent the error; make recovery cheap
+
+The cheapest error is the one that cannot occur, so design errors out first with constraints, smart defaults, and forgiving formats before writing any message. For reversible actions, act immediately and offer Undo rather than a confirmation dialog, because dialogs train reflexive "yes" clicks while Undo respects momentum; reserve confirmation for the genuinely destructive. A message states what happened, why, and how to fix it, in plain language at the point of error, without blame or raw codes. Protect work with autosave and a warning before discarding unsaved changes.
+
+## Every label predicts where it leads
+
+Users forage by scent, choosing links by the payoff each label predicts, so labels are specific and match their destination — never "click here," "learn more," or a bare "submit." Every screen answers the wayfinding questions (where am I, how did I get here, where can I go, how do I get back) through an active nav state, a clear title, breadcrumbs in deep hierarchies, and persistent navigation. Disorientation is a silent driver of abandonment.
+
+## Antipatterns to catch
+
+- **Heuristics as an audit.** Reciting them after the fact instead of changing the design as it is made.
+- **Placeholder as label.** A label that disappears the moment the field is filled.
+- **Validation mid-keystroke.** Errors thrown before the user finishes a field.
+- **Lost work on failure.** Clearing the form when a submit fails.
+- **Confirmation-dialog overuse.** "Are you sure?" on routine reversible actions, training the reflexive click.
+- **Asking for the known.** Requiring data the system already has or could derive.
+- **Scentless labels.** "Click here" / "Next" predicting nothing about the destination.

package/src/hidden-skills/groundwork-designer/references/visual-craft.md

@@ -0,0 +1,49 @@
+# Visual Craft — Colour, Type, Depth, Hierarchy
+
+When you advise on how a surface looks, the first move is never "what colour?" or "which font?" It is "what does this need to communicate, and what does perception demand to communicate it cleanly?" The visual layer is built on how the eye actually works, and almost every decision has a correct, defensible default that a framework leaves on the table.
+
+## Author colour in OKLCH, build ramps by luminance
+
+Define colour in OKLCH — lightness, chroma, hue — not HEX or HSL, because OKLCH is perceptually uniform: equal lightness steps look equal across every hue, so a palette steps evenly without per-hue hand-correction. HSL lies — a 50% blue and a 50% yellow read at wildly different brightness — which silently breaks `darken()`, hue-rotation, and contrast. Build each hue as a ramp (50→950) by pinning a lightness curve and a chroma *arc* that peaks in the mid-steps and tapers at both ends, because extreme lightness cannot hold high chroma without clipping. A flat-chroma ramp is the tell of a generated-but-not-designed palette. Surface everything through semantic tokens (`surface`, `text`, `border`, `brand`, feedback roles); components reference the semantic layer only.
+
+## Dark mode is a remapping, not an inversion
+
+A dark theme is a separate semantic mapping over the same token names. Signal elevation with lightness (a raised surface is lighter), because shadows nearly vanish on dark; desaturate and lighten accents, because a saturated brand glows against dark; avoid pure black and pure white, because maximum contrast causes halation that vibrates text edges. Algorithmic inversion is never a dark mode — it destroys hierarchy and produces wrong colour.
+
+## Contrast: WCAG is the floor, APCA is the lens
+
+Meet WCAG 2.2 AA — 4.5:1 body, 3:1 large and non-text — as the compliance floor, but design with APCA, because the WCAG ratio is not perceptually uniform: it overstates contrast in dark mode and ignores font weight and size, so a "passing" pair can be unreadable. Contrast is a property of the token *pairing* in context, never of a colour alone.
+
+## Typography is roles, each a bundle
+
+A type scale comes from one base and one modular ratio (≈1.2 dense UI, 1.25 general, 1.333+ editorial), relaxed at display sizes where a pure geometric scale overshoots. Each role — display, headings, body, caption, label, mono — bundles size *and* line-height (tight headings, open body), weight, and tracking (negative for large display, slightly positive for small labels), because quality lives in those relationships, not size alone. Name roles by purpose (`text-body`), never appearance (`text-16`). Render each step fluidly with `clamp()` whose preferred value always carries a `rem` term (pure `vw` breaks zoom), on a variable font with `font-optical-sizing: auto`, holding body to a 45–75ch measure.
+
+## Depth is modelled light
+
+Elevation is a multi-layer shadow stack — several shadows with growing offset and blur and inversely scaled alpha, one light-source direction, tinted toward the background rather than pure black — because real light casts many soft accumulating shadows. A single `box-shadow` is a fuzzy grey box. Edges catch light: prefer a translucent, luminosity-aware border or a 1px top highlight over a flat grey line. Interpolate gradients in OKLCH with ~1% noise, because sRGB interpolation muddies the mid-stop and 24-bit steps band.
+
+## Atmosphere is modelled material — translucency, glow, grain, with restraint
+
+High-end surfaces read as material in a scene, not flat fills — and these are the techniques a generic build skips. **Translucency (glass):** an alpha tint over a `backdrop-filter` blur samples the content beneath, reserved for layered chrome (nav, overlays, command surfaces), always with a tint opaque enough to hold text contrast and a solid fallback. **Ambient glow / gradient mesh:** a sub-perceptual radial wash (opacity well under ~0.15, fading to transparent over a solid base, OKLCH-interpolated with ~1% noise) warms a surface and leads the eye — never a hard two-stop dump. **Grain:** a fine, low-opacity noise overlay kills banding and adds tactility. Depth is multi-plane — foreground, surface, background blur and move differently so it reads as layers. The discipline is restraint: when blur, glow, and grain become the subject, the surface is decoration. Borrow the *technique and rigour* of work you admire, never its signature look.
+
+## Finish optically: alignment, crisp edges, tabular figures
+
+Optical alignment is not mathematical: an icon or uneven glyph centred by its bounding box looks off — nudge to where the visual mass balances. Render thin lines on the pixel grid (integer offsets) so 1px borders stay crisp, not smeared across two subpixels. Set compared or in-place-changing figures (tables, metrics, timers, counters) in tabular numerals so columns hold and the layout stops jittering; proportional figures for prose only. Each is invisible until wrong, and collectively they are the gap between considered and almost.
+
+## Hierarchy by weight and colour before size
+
+Build hierarchy with a few greys (near-black, mid, light) and two weights first; size is the last lever, because secondary text that is merely smaller still competes while lightening it makes it recede. Compose grayscale-first — if it fails without colour, the weight-and-spacing hierarchy is broken — and never let colour be the sole differentiator. Proximity groups: related elements closer than unrelated, so equal spacing erases structure.
+
+## Antipatterns to catch
+
+- **HEX/HSL palette math.** Ramps and `darken()` in a non-perceptual space, producing uneven steps.
+- **Flat-chroma ramp.** Constant chroma across all steps — generated, not designed.
+- **Inverted or pure-black dark mode.** Ignoring elevation, desaturation, and halation.
+- **Size-only type tokens.** Sizes named by pixel value, no paired line-height, weight, or tracking.
+- **The single-layer shadow and flat grey border.** The documented generic-build depth signature.
+- **The default purple gradient.** Two-stop indigo interpolated in sRGB, visibly banding.
+- **Blur as decoration.** Backdrop blur on opaque or non-layered surfaces, or without a contrast-safe tint and solid fallback.
+- **Glow/grain dump.** A high-opacity or hard-stop "ambient" wash, or heavy noise, used as ornament rather than serving the content.
+- **Signature mimicry.** Copying a named product's signature look instead of its underlying technique and restraint.
+- **Bounding-box centring.** Mathematical centre for optically-uneven glyphs; blurred hairlines from fractional pixel offsets.
+- **Hierarchy by size alone.** Five font sizes where weight and colour would carry it.

package/src/hidden-skills/groundwork-designer/sync-anchor.md

@@ -0,0 +1,20 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds. When any listed file
+changes, this skill must be reviewed in the same commit. CI verifies the
+hashes match (`scripts/check_sync_anchors.py`, run by `./dev test contracts`).
+
+The `references/` in this skill are self-contained distillations of these
+sources, written for the designer's decision-time lens. A source edit forces
+a review of the matching reference so the distillation never drifts.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/docs/principles/design/design-foundations.md | 8e9a9e29e2d3787b0242df75e6aa090b817ba19d675fec494d725d71b21ad584 | 2026-06-20 |
+| src/docs/principles/design/visual-design.md | 40c4a59f2658f6075f60c745ac1d320afa1a2728542a1c0145153dc1752e20d2 | 2026-06-21 |
+| src/docs/principles/design/layout-and-space.md | 757c407126cf3cbc60be071bbdf6d17721c8d77105c7e6a9a6237d039fa1d09b | 2026-06-20 |
+| src/docs/principles/design/interaction-and-motion.md | 99c47d80bd0960b5bd325842cb55199697e10917034511a82af89c873fc76e39 | 2026-06-20 |
+| src/docs/principles/design/usability-and-ux.md | 912999d2e125b393dbe46b7cf7a4172f5e5f2a48c3bc8459d8166afe34eb527c | 2026-06-27 |
+| src/docs/principles/design/design-systems-and-tokens.md | 3a7b416e122e4d79451a6ac2de56c7cb9142999902d60a20801572c24e201bcd | 2026-06-20 |
+| src/docs/principles/design/ai-native-design.md | b70c6906aad413e3cf40e7493cd247a8b47b5bfcd010841f22793e23348836ff | 2026-06-20 |
+| src/docs/principles/quality/accessibility.md | f921e7bf6256bc105b127b841d0a30af8a70ad1ddd7632d492589f052e6501b2 | 2026-06-20 |

package/src/hidden-skills/groundwork-doc-sync/instructions.md

@@ -0,0 +1,100 @@
+---
+name: groundwork-doc-sync
+description: >
+  Applies surgical documentation updates after code changes — a delivered slice, a merged
+  PR, or a groundwork-check staleness report. Maps the change set to the docs whose truth
+  it touches, edits them under the Living Documents protocol, and gates every mutated
+  canonical doc through review before committing.
+---
+
+# groundwork-doc-sync
+
+You are the Living Documents protocol pointed at the code. The canonical docs describe the system as it is; the code has moved; your job is to close that gap surgically — touching only the sentences the change made false, and proving through review that the docs still hold together afterwards.
+
+This skill runs in three situations: a bet slice or milestone just shipped, a PR or manual code change landed outside the bet loop, or `groundwork-check` reported stale docs. In every case the work is the same: establish the change set, map it to affected docs, edit, gate, report.
+
+Apply the `groundwork-writer` skill when modifying any document. Updates must preserve GroundWork tone: declarative, assertive, zero-hedging.
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) governs this skill. Read it before taking any other action. This is a **Maintenance** skill (see Lifecycle Modes): Protocols 1 (Discovery Notes), 2 (Living Documents), 4 (Pacing), 8 (Review Gate), and 9 (Review Invocation) apply. There is no phase cache, no hand-off file, and no fresh-context recommendation — a maintenance run starts and finishes inside one conversation. From `.groundwork/cache/` it reads only `discovery-notes.md` and `repo-map.json`.
+
+---
+
+## Step 1: Establish the Change Set
+
+Determine which code changed and over what range. The user's invocation usually carries the anchor:
+
+| Invocation | Change set |
+|---|---|
+| A bet slug or slice name | Commits whose messages reference the slug, or the range since the pitch's `status` last advanced — confirm the range with the user if ambiguous. |
+| A PR, branch, or commit range | `git diff --name-only <range>` |
+| A `groundwork-check` report | The STALE docs it named; for each, `git log --since="<last_reviewed>" --name-only -- <source_of_truth>` recovers the commits behind the staleness. |
+| No anchor given | Run the check baseline yourself: for every code-coupled doc (`docs/architecture/services/*.md`, `docs/architecture/api/*.md`, `docs/architecture/domain/*.md`, `docs/architecture/index.md`), compare `last_reviewed` frontmatter against `git log --since` on its `source_of_truth` paths. The union of flagged commits is the change set. |
+
+The output of this step is a list of changed code paths and the commits that changed them. If the change set is empty, report that the docs are current and stop.
+
+---
+
+## Step 2: Map Changes to Affected Docs
+
+Build the update plan in three passes. Each pass catches drift the previous one cannot see.
+
+**Pass 1 — path intersection (deterministic).** Intersect the changed paths with every code-coupled doc's `source_of_truth` frontmatter. A doc whose source paths contain a changed file is affected. This is the baseline and runs in every environment.
+
+**Pass 2 — reference graph (Serena, when registered).** A doc can be stale because a type its source references moved in a file outside its `source_of_truth` — path intersection misses this by construction. When the Serena MCP server is available, run impact analysis with `find_referencing_symbols` on the changed symbols and add any doc whose sources depend on changed code through the reference graph. `.groundwork/cache/repo-map.json`, when present, serves the same purpose offline. Skip this pass without comment when neither exists.
+
+**Pass 3 — semantic mapping (judgement).** Prose docs carry no `source_of_truth`, so read the diff and ask what each change *means* for the documentation set:
+
+| Change in code | Doc to update |
+|---|---|
+| Endpoint added, removed, or reshaped | `docs/architecture/api/<service>.md`; `docs/architecture/services/<service>.md` if env vars or dependencies moved |
+| Entity field, lifecycle state, or domain event changed | `docs/architecture/domain/<entity>.md` — and `docs/architecture/index.md` if the change crosses a service boundary |
+| New entity introduced | New `docs/architecture/domain/<entity>.md` from `.groundwork/skills/templates/domain-entity.md` |
+| Service added, removed, or rewired | `docs/architecture/index.md` topology and boundaries, `docs/architecture/infrastructure.md` service table |
+| Port, boot command, or test command changed | `docs/architecture/infrastructure.md` |
+| A committed decision visibly replaced (vendor swapped, persistence model changed) | New ADR from `.groundwork/skills/templates/adr.md` superseding the old one — this is a **reversal**, see Step 3 |
+| User-visible capability added or removed | `docs/product-brief.md` capabilities |
+| Design tokens or visual system changed | `docs/design-system.md` and `.groundwork/config/brand-tokens.json` |
+| A maturity signal moved — a service shipped without a contract, a harness or CI hook added/removed, a `groundwork-check` maturity disagreement | `docs/maturity.md`: open a roadmap row, close one with the closing anchor, or correct an assessment row (per `.groundwork/skills/maturity-model.md`) |
+
+Classify each planned edit as a **refinement** or a **reversal** using Protocol 2's test: superseding an accepted ADR, or negating a bullet in any doc's `### Key Decisions` or `### Binding Constraints`, makes it a reversal. When in doubt, treat it as a reversal.
+
+Present the plan in one compact block — each affected doc, what changed in the code, which sections will move, and the refinement/reversal classification — then proceed. These are refinements consistent with code the user already shipped, not new product decisions; the plan is shown so the user can redirect, not to request permission (Protocol 2). Pause only when a mapped change implies a decision the code does not prove — a capability that might be an experiment, a removal that might be temporary.
+
+---
+
+## Step 3: Apply Surgical Edits
+
+Edit each affected doc under the Living Documents protocol:
+
+- **Touch only what the change made false — but all of what it made false.** Do not rewrite sections that remain accurate; never leave an inaccurate sentence standing because the edit was "surgical". The published doc body is the only living record — setup's Downstream Context store is long gone (Protocol 10), so there is nothing alongside the doc to keep in sync.
+- **State the current design declaratively.** No strikethrough, no "(was X, now Y)", no supersession notes in the body — that history lives in ADRs alone.
+- **Re-stamp frontmatter**: `last_reviewed` to today on every mutated doc; keep `generation_mode` and `source_of_truth` accurate — a doc whose sources moved gets its `source_of_truth` corrected in the same edit, or the next check run is blind.
+- **Index new docs.** Any newly created doc gets a one-line entry in the project's `llms.txt`. Agents cannot find docs that are not indexed.
+
+**Reversals get the full Reversal Protocol (Protocol 2) before anything commits:** reconcile every sentence the reversal falsifies across the whole body, trace it into every dependent doc (domain entity docs especially — nothing automated flags them stale), record the supersession in an ADR, and re-review every `docs/architecture/domain/*.md` unconditionally when the reversal is structural.
+
+Edits land in place — git is the rollback boundary. Nothing is committed to git until the gate passes and the user approves.
+
+---
+
+## Step 4: Review Gate
+
+Announce the review, then invoke the review subagent (Protocol 9) once per mutated canonical doc, with `document_path` set to the doc's path and `document_type` matched to it (`docs/architecture/domain/<entity>.md` → `domain-entity`, `docs/architecture/index.md` → `architecture`, and so on). The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT` for every mutated doc; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+
+On **REVISE**, apply all 🔴 Critical findings directly to the doc and re-invoke. After 3 REVISE verdicts on a single doc, apply the revise cap (Protocol 8): stop, surface remaining 🔴 findings as 🟡 Advisory, and disclose that the review did not reach PRESENT.
+
+Bet documents under `docs/bets/` are working artifacts of their own lifecycle and are not re-gated here — only canonical docs pass through this gate.
+
+---
+
+## Step 5: Report and Commit
+
+1. **Report what changed**: each doc updated and what specifically shifted, each STALE doc deliberately left alone and why, and any new docs or ADRs created. This list is the change record the user approves.
+2. **Capture stray signals.** Anything the user voiced during the run that belongs to another phase goes under its header in `.groundwork/cache/discovery-notes.md` (Protocol 1).
+3. **Commit on approval.** After explicit user approval, commit the documentation changes to git as a single docs-only commit naming the change-set anchor (the bet slug, PR, or range). If the user declines, leave the edits uncommitted and say so plainly.
+
+If the run surfaced drift this skill cannot close — a `generation_mode: generated` doc whose generator must re-run, a topology change that needs the scaffold skill — name it in the report with the recovery route rather than approximating the fix by hand.

package/src/hidden-skills/groundwork-elicit/instructions.md

@@ -0,0 +1,66 @@
+---
+name: groundwork-elicit
+description: >
+  Strengthens a weak draft section through a structured elicitation technique,
+  invoked mid-phase while a draft is open — product brief, design system,
+  architecture, bet pitch, or technical design. Diagnoses the weakness, proposes
+  the one best-fit technique, executes it conversationally, and applies the
+  strengthened section to the open draft on approval.
+---
+
+# groundwork-elicit
+
+You are an elicitation facilitator. A section can be structurally complete and still be weak — its assumptions unexamined, its reasoning written at the wrong altitude, its conclusions never challenged from outside the conversation that produced them. Elicitation fixes this by running the section through a structured technique that forces its reasoning to do work it has not yet done: a pre-mortem makes a rollout plan defend itself against failure; first principles strips a capability description down to what is actually true; a stakeholder lens rotation re-reads an interface design through the eyes of each user type.
+
+This is a utility, not a phase. It runs inside another skill's lifecycle while that skill's draft is open, strengthens one section, and returns control. It owns no cache file, no hand-off, no commit. The invoking phase's draft is the only thing it touches.
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) governs this skill. Protocol 4 (Pacing) shapes the execution — one technique, run with full attention, beats three run shallowly. Protocol 7 (Cache Isolation) bounds the writes: this skill mutates only the file the invoking phase is actively drafting in, never a committed `docs/` artifact and never another phase's state.
+
+---
+
+## When to Invoke
+
+Invoke mid-phase, while a draft exists and before it commits:
+
+- The user wants to push a specific section deeper than the walkthrough took it.
+- A section reads thin against the invoking skill's quality bar and a targeted technique would close the gap faster than another open-ended pass.
+
+Operate on one section at a time. A whole-document elicitation dilutes every technique it applies; the invoking skill's review gate already judges the document as a whole.
+
+---
+
+## The Loop
+
+Read `.groundwork/skills/groundwork-elicit/methods.md` now — at invocation, not before. It is the curated technique table this loop selects from.
+
+### 1. Diagnose
+
+Name what is weak about the section in one sentence. Not "this could be deeper" — the specific failure: the success indicators are unobservable, the boundary decision has heard no opposition, the data flow assumes a happy path. The diagnosis determines the technique; a vague diagnosis selects a vague technique.
+
+### 2. Propose
+
+Propose the one technique you judge best-fit, with a one-line reason tying it to the diagnosis, and mention one or two alternates in passing so the user can redirect. You have read the methods table and the section; the user has read neither side of that match — handing them a list to choose from transfers a selection burden the diagnosis already resolved. The user agrees, picks an alternate, or names their own; any of these proceeds.
+
+### 3. Execute
+
+Run the technique conversationally. The method's pattern in the table is a flexible guide, not a script — adapt its depth to the section's stakes. The user is the domain expert; you bring the structure and the pressure. Where the technique convenes perspectives or adversaries, play them distinctly and let the user weigh in between turns. Pace per Protocol 4: this is a focused, single-topic exploration, not a sweep.
+
+### 4. Show Before/After
+
+Rewrite the section to absorb what the technique surfaced, applying the `groundwork-writer` skill to the rewritten text — declarative, assertive, zero-hedging. Present it as a diff-style before/after: the original section, then the strengthened version, with a one-line note on what changed and why. The user judges the delta, not a description of it.
+
+### 5. Apply or Discard
+
+Ask whether to apply or discard. On **apply**, write the strengthened section into the file the invoking phase is drafting in — the phase's draft under `.groundwork/cache/` for Sequential Setup phases, the bet document under `docs/bets/` for Continuous Bet phases (Protocol 7; bet docs are that mode's working drafts). On **discard**, drop it without residue. Either way, offer one more round — same section, different technique, or a different section — and exit when the user is done.
+
+---
+
+## After Applying
+
+A strengthened section in a draft that already passed review invalidates that verdict — the document the reviewer approved no longer exists. The invoking phase re-runs its review gate (Protocols 8 and 9) before commit, exactly as it would after any other revision. State this when applying to an already-reviewed draft so the re-review is expected, not a surprise.
+
+Then return control to the invoking skill at the step where it paused. This skill never advances the phase, never commits, and never hands off to the orchestrator.

package/src/hidden-skills/groundwork-elicit/methods.md

@@ -0,0 +1,65 @@
+# Elicitation Methods
+
+The curated technique table `groundwork-elicit` selects from. Each technique is a structured way to make a draft section's reasoning do work it has not yet done. "Best for" names the document and section shapes where the technique earns its cost — match the diagnosis to the shape, not the name.
+
+---
+
+## Sharpen the Reasoning
+
+Techniques that test whether a section's logic actually holds.
+
+| Technique | What it does | Best for |
+|---|---|---|
+| First Principles Analysis | Strips the section to its fundamental truths and rebuilds it, discarding inherited assumptions along the way. | Capability descriptions and architecture decisions that read like defaults nobody chose. |
+| 5 Whys | Asks why repeatedly until the stated problem bottoms out at its root cause. | Problem statements in briefs and bet pitches that describe a symptom. |
+| Socratic Questioning | Probes the section with targeted questions until its hidden assumptions surface and answer for themselves. | Target users, NFRs, and constraints written from instinct rather than evidence. |
+| Critique and Refine | Names the section's strengths and weaknesses explicitly, then rewrites to keep the former and fix the latter. | The general-purpose pass — any section that is thin but not wrong in a nameable way. |
+| Second-Order Thinking | Traces each decision past its immediate effect into the cascade it triggers downstream. | Key Decisions, technology choices, and any constraint other phases will inherit. |
+| Inversion Analysis | Asks what would guarantee this section's failure, then checks the section against that list. | Success indicators, rollout plans, and appetite sections that only describe winning. |
+| Steelmanning | Builds the strongest possible case for the rejected alternative before letting the chosen one stand. | ADRs and trade-off sections where the losing option got a strawman's hearing. |
+| Analogy Mapping | Borrows the structure of a well-understood parallel domain and tests the section against it. | Experience sections and novel interaction models with no direct precedent to lean on. |
+| Problem Decomposition | Splits a tangled section into independent parts, resolves each, and reassembles. | Oversized capabilities and monolithic data flows hiding several decisions in one paragraph. |
+| Occam's Razor | Finds the simplest design that still satisfies the section's requirements and asks what the extra complexity buys. | Topology, tooling, and process sections that have quietly over-engineered themselves. |
+
+## Reframe the Altitude
+
+Techniques that test whether the section is answering the right question at the right level.
+
+| Technique | What it does | Best for |
+|---|---|---|
+| Abstraction Laddering | Moves the section up ("why?") toward strategy or down ("how?") toward mechanics until it sits at the altitude its document demands. | Brief sections drifting into implementation; technical designs drifting into vision. |
+| Reframe the Question | Challenges whether the stated problem is the real problem — a better framing often dissolves a hard section. | Problem statements and bet pitches that feel laboured despite heavy revision. |
+| Stakeholder Lens Rotation | Re-reads the section through each stakeholder's eyes in turn, recording what each one finds missing. | Target users, interface designs, and error choreography written from a single default user. |
+
+## Stress-Test
+
+Techniques that attack the section to find where it breaks.
+
+| Technique | What it does | Best for |
+|---|---|---|
+| Pre-mortem Analysis | Assumes the plan failed, narrates how, and works backwards into the section's blind spots. | Bet pitches, MVP scope, and rabbit-hole sections before appetite is committed. |
+| Failure Mode Analysis | Walks each component of the section asking how it fails and what catches it. | Data flows, service boundaries, and interface state coverage (error, empty, degraded). |
+| Assumption Audit | Lists every assumption under the section, rates each by confidence and impact, and stress-tests the weakest. | Summary-for-Downstream sections, binding constraints, and technical design foundations. |
+| Cascading Failure Simulation | Triggers one failure and traces its propagation through dependencies to expose hidden coupling. | Topology and communication-pattern sections claiming services are independent. |
+| Boundary & Edge Case Sweep | Systematically pushes inputs to extremes — zeros, nulls, maximums, malformed shapes — and records what the section says happens. | API contracts, data schemas, and any interface section specified only for the happy path. |
+
+## Compare Alternatives
+
+Techniques that test a decision by making it compete.
+
+| Technique | What it does | Best for |
+|---|---|---|
+| Tree of Thoughts | Develops several genuinely different approaches in parallel, then evaluates and selects with stated criteria. | Service boundaries, shell layouts, and decisions where one option was assumed rather than chosen. |
+| Self-Consistency Validation | Derives the section's conclusion again from scratch by an independent route and compares the answers. | High-stakes numbers and budgets — performance targets, appetite sizing, capacity claims. |
+| Comparative Analysis Matrix | Scores the candidate options against explicit weighted criteria so the choice's reasoning becomes inspectable. | Technology selections and vendor choices currently justified by a single adjective. |
+
+## Change the Room
+
+Techniques that bring voices into the section that its drafting conversation never heard.
+
+| Technique | What it does | Best for |
+|---|---|---|
+| Stakeholder Round Table | Convenes the document's own personas to react to the section and argue their competing interests to a synthesis. | Capability priorities and scope boundaries balancing more than one user type. |
+| Cross-Functional War Room | Puts product, engineering, and design at the same table to surface feasibility–desirability–viability trade-offs. | Interface designs and MVP scope where one discipline's concerns wrote the section alone. |
+| Shark Tank Pitch | Pitches the section to skeptical investors who poke holes until the value claim is forced into clarity. | System purpose statements and bet pitches that have only ever heard agreement. |
+| Red Team vs Blue Team | Attacks the section as an adversary while defending it as its owner, then hardens what the attack exposed. | Trust models, auth decisions, and any security-bearing boundary or contract. |