Uxcel-Lab/product-skills

# Assumption Rigor Audit Skill

## What this skill changes vs. default behavior

By default, Claude accepts validation at face value — "we ran a survey and users liked it, so it's validated" passes without challenge. It rarely asks whether the *riskiest* assumption was the one tested, whether the method was strong enough for the decision it's meant to support, whether "would you use this?" answers were mistaken for evidence, whether success was defined *before* the test, or whether the sample was big enough to mean anything. This audit forces four things: every finding names the violated principle; the *decision the test is meant to support* is the unit of judgment (rigor scales to what's at stake); evidence claims are tested for signal vs. noise; and findings come severity-rated by decision damage with a concrete fix.

This is an **evaluative** skill: it auto-runs whenever a validation plan, experiment, discovery approach, or a "we validated…" claim is being reviewed — and as the validation step after `pm-assumption-testing` produces a test plan.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when the `pm-product-review` orchestrator or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **the always-relevant PM lens — auto-runs**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# Decision Quality Audit Skill

## What this skill changes vs. default behavior

By default, Claude evaluates a decision by its result — if the launch worked, the call was good — and accepts a confident rationale at face value. It rarely separates the quality of the *reasoning* from the luck of the *outcome*, checks whether the deliberation matched how reversible the decision was, names the bias quietly driving the choice, or asks whether failure modes were surfaced before commitment. This audit forces four things: every finding names the violated principle; decisions are judged on the reasoning available *at the time*, not hindsight; the bias or process gap is named explicitly with a structural countermeasure; and findings come severity-rated by decision damage and reversibility with a concrete fix.

This is an **evaluative** skill: it auto-runs whenever a significant product decision, decision log, or retrospective is being reviewed — and as a validation step after a consequential call is made.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when the `pm-product-review` orchestrator or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **an artifact-specific lens — offered (for high-stakes, hard-to-reverse decisions)**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# OKR & Metric Validity Audit Skill

## What this skill changes vs. default behavior

By default, Claude reviews OKRs by polishing wording and nodding at structure — it rarely challenges whether a key result is *falsifiable*, whether a metric is *vanity*, whether an "objective" is just a feature launch in disguise, or whether hitting the target could actually *harm* the product. This audit forces four things: every finding names the violated principle, every metric is tested for decision-usefulness ("what would we do differently if this number changed?"), every optimization target is checked for gaming exposure and guardrails, and findings come severity-rated with concrete rewrites — not general encouragement.

This is an **evaluative** skill: it auto-runs whenever OKRs, KPIs, or success metrics are present in work being reviewed or generated.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when the `pm-product-review` orchestrator or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **an artifact-specific lens — offered (when metrics/OKRs are defined)**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# Prioritization Rigor Audit Skill

## What this skill changes vs. default behavior

By default, Claude *performs* prioritization confidently — it fills RICE tables with invented numbers, ranks features by plausible-sounding impact, and presents the result with unearned precision. Reviewing someone else's prioritization, it tends to accept scores at face value. This audit forces four things: every score is traced to its evidence (or flagged as decoration), every ranking is traced to a strategic outcome (or flagged as unmoored), every "must-have" is challenged, and every decision is checked for an explicit, stress-tested trade-off. Findings come severity-rated with concrete fixes.

This is an **evaluative** skill: it auto-runs whenever a prioritized list, scoring table, backlog order, or build-next decision appears in work being reviewed or generated.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when the `pm-product-review` orchestrator or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **an artifact-specific lens — offered (when work is prioritized or roadmapped)**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# Spec Quality Audit Skill

## What this skill changes vs. default behavior

By default, Claude reviews a spec by praising its structure and suggesting wording polish — it rarely tests whether a requirement is *buildable as written*, whether different teams would interpret it differently, whether the document quietly skipped what's **out** of scope, or whether "validated" claims have any evidence behind them. This audit forces four things: every finding names the violated principle; every requirement is tested with "could QA write a pass/fail check from this without asking what you meant?"; the document is checked for what's *missing* (scope exclusions, DCA, corner cases), not just what's present; and findings come severity-rated by build damage with concrete rewrites.

This is an **evaluative** skill: it auto-runs whenever a spec, PRD, or requirements document is being reviewed — and as the validation step after `pm-product-spec` generates one.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when the `pm-product-review` orchestrator or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **an artifact-specific lens — offered (for specs/PRDs)**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# Competitive Analysis Skill

## How this skill behaves (read first)

This is a **generative** skill, and "do a competitive analysis" is where an AI assistant produces the most confident, least useful output: a flat feature-comparison table of the few obvious direct competitors, with invented specifics, no market context, no gaps identified, and no "so what." Two failure modes compound it — **fabricated competitor facts** (made-up features, pricing, or market share that read as authoritative) and **no strategic conclusion** (a report that lists but never decides). A real competitive analysis is **scoped to a decision, grounded in honest public evidence, structured by the right framework, and ends in implications and a positioning choice**. So this skill gates:

1. **Establish the research objective and the industry context** — what decision this informs, and the market it sits in, so competitor moves are read in context rather than in a vacuum.
2. **Apply the always-true core** — find all three competitor types, profile from real public sources, use the right framework, prioritize, and translate into strategic implications and a position.
3. **Surface the context-dependent decisions** (which framework, primary vs. secondary research, competitor depth, positioning stance, expansion, AI's role) with trade-offs.

Then it **hands off to `pm-assumption-rigor-audit`** (are the competitor facts, market-size estimates, and "gap exists" claims evidenced or assumed/hallucinated?) and **`pm-prioritization-rigor-audit`** (when it ranks opportunities or competitor tiers).

Scope: this skill owns the **competitive/market analysis and the positioning conclusion that follows from it**. It defers full **product strategy** to `pm-vision-strategy`, **pricing strategy** to `ux-pricing`, **go-to-market / market-entry timing** to `pm-gtm-plan`, the broader **research process and ethics** to `pm-discovery`, and **problem framing** to `pm-problem-statement`.

# Go-to-Market Plan Skill

## How this skill behaves (read first)

This is a **generative** deliverable skill, and "write a GTM plan" is where an AI assistant defaults to a **generic launch checklist** — announce, blog post, social, email, press — with no strategy underneath. The deeper mistakes: treating GTM as a **one-time launch** rather than a living system, **stage-skipping** (bolting a reseller network or paid-acquisition engine onto a company with 8 customers), ignoring **timing** (seasonality, B2B budget cycles, market readiness), and **funnel-forcing** buyers through a pipeline on the company's schedule. A GTM plan that doesn't fit the company's stage burns the resources that should be going to the actual foundational work.

So this skill gates hard:

1. **Establish context** — GTM readiness (is demand validated?), company maturity stage, customer/business-model type, and timing conditions.
2. **Apply the always-true core** — GTM as a system of five interlocking components, stage-appropriate execution, channel-as-cost-structure, timing awareness, non-linear buyer journey.
3. **Surface the context-dependent decisions** (stage tactics, channel model, business-model motion, entry timing, partnerships) with trade-offs; let the user choose.

Then it **hands off to `pm-okr-metric-validity-audit`** (are the launch metrics valid, not vanity?) and **`pm-assumption-rigor-audit`** (is demand really validated, is the timing window real, will the channel actually work?).

# OKRs & KPIs Skill

## How this skill behaves (read first)

Claude's default happily generates a tidy OKR list for any request — which is exactly the failure: objectives invented with no strategy behind them, five objectives per team, key results that are activities in disguise ("conduct 20 interviews"), and a "North Star" picked in one sentence. Goals written this way actively misdirect a team for a quarter.

So this skill is **generative but gated**:

1. **Establish context** — strategy, level, cycle, and what data exists. No strategy → say so and work at the right level instead of inventing one.
2. **Apply the always-true core** — outcome KRs with baseline/target/timeframe, one focus objective, leading+lagging mix.
3. **Surface the context-dependent decisions** — framework weight, North Star, cadence, cascading model — with trade-offs; let the user choose.

Then it **hands the result to `pm-okr-metric-validity-audit`** for validation.

# Product Spec / PRD Writer Skill


## How this skill behaves (read first)

Claude's default already produces a *plausible-looking* PRD on request — which is exactly the problem. The default tends to: invent requirements before the problem is pinned down, write vague targets ("fast", "user-friendly"), skip dependencies and assumptions, and phrase user stories as engineering tasks. A document that looks complete but is built on an unvalidated problem and untestable requirements is worse than no document, because teams build from it.

So this skill is **generative but gated**, and it enforces quality rather than just filling a template:

1. **Gate on the problem first.** Don't draft requirements until there's a clear, fact-based problem statement. If the user hasn't supplied one, build it with them — or flag that the spec rests on unverified assumptions.
2. **Write the right document.** PRD and spec are different artifacts for different audiences and moments — pick deliberately (see below).
3. **Enforce measurability.** Every requirement must be testable; every user story must express value; every assumption must be flagged as a risk.
4. **Self-audit before delivering** (built-in review pass — see final section).

# Product Roadmap Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure mode is the **dated feature list**: features pinned to months, presented as commitments, mistaken for a backlog, stale within a quarter — manufacturing an illusion of certainty that converts every market shift into a broken promise. A roadmap is a *strategic communication tool*: it answers why and what-outcome, in sequence, at the right confidence level. This skill gates:

1. **Establish strategy, audience, and horizon** — these decide format, detail, and date precision.
2. **Apply the always-true core** — outcomes over outputs, themes over features, strategy linkage, honest uncertainty.
3. **Surface the format and process decisions** (Now-Next-Later vs. timeline, quarterly vs. annual, audience views) with trade-offs.

Then it **hands off to `pm-prioritization-rigor-audit` and `pm-okr-metric-validity-audit`** for validation.

---

# Product Vision & Strategy Skill

## How this skill behaves (read first)

This is a **generative** skill, and vision/strategy is where an AI assistant produces its most confident, least useful output. Two default failure modes dominate:

1. **The inspirational poster.** Asked for a vision, Claude writes a buzzword sentence — "be the world's most loved, best-in-class platform that delights customers with seamless experiences" — that sounds good and guides zero decisions. If *any* feature can be justified by it, it's too vague to be a vision.
2. **Conflation and feature-listing.** Claude treats vision, strategy, roadmap, and mission as interchangeable, and writes "strategy" as a list of features to build rather than a set of deliberate choices about where to play, how to win, and **what not to do**. Strategy that targets "everyone" and skips trade-offs isn't strategy.

A real vision is a **specific, stable, user-centric destination**; a real strategy is a **focused set of interconnected, trade-off-driven choices** grounded in evidence and tied to outcomes. So this skill gates:

1. **Establish context** — vision, strategy, or both; company shape; product stage; market type; altitude.
2. **Apply the always-true core** — the artifact distinctions, the laddering, the focus-and-trade-off discipline, the stability rule.
3. **Surface the context-dependent decisions** (which framework, which communication format, portfolio/B2B/stage/depth) with trade-offs, and let the user choose. Running every framework at once is the failure mode.

# Personas & Jobs-to-Be-Done Skill

## How this skill behaves (read first)

This is a **generative** skill, and personas are where an AI assistant is most tempted to do exactly the wrong thing. Asked to "make some personas," the default is to invent plausible demographic fiction — "Sarah, 32, marketing manager, loves yoga and oat-milk lattes" — with no research basis, needs *inferred from* demographics, and a pile of irrelevant lifestyle detail. Uxcel's own source is blunt about it: LLM-generated personas reflect generic internet stereotypes and underrepresent edge cases and minority users. A useful persona instead **synthesizes real research into a memorable character whose every detail could change a design decision** — or, when what matters is the *progress a user is trying to make*, a **Job-to-Be-Done** is the better lens. So this skill gates:

1. **Establish the research objective, the stage/data you have, and the resources** — these decide whether to use personas, JTBD, or both, and whether you even have the evidence to build one yet.
2. **Apply the always-true core** — ground in real research, keep only decision-relevant detail, use JTBD for the job and personas for the who, keep the set small, build as a team, and keep it alive.
3. **Surface the context-dependent decisions** (lens choice, research-based vs. proto, count, which details, segmentation depth, AI's role) with trade-offs.

Then it **hands off to `pm-assumption-rigor-audit`** — the check that the persona's claimed needs and behaviors rest on evidence, not assumption.

Scope: this skill owns the **audience-understanding artifact**. It defers the **research process that feeds it** to `pm-discovery` (including ethical/inclusive recruitment), **framing the user problem** to `pm-problem-statement`, **turning a persona + job into stories** to `pm-user-story`, and **behavioral/cohort analytics depth** to `pm-analytics`.

# Problem Statement Skill

## How this skill behaves (read first)

This is a **generative** skill, and a problem statement is where most product work quietly goes wrong. Claude's default is to restate a request as a problem and move on — producing the four classic failures: a **solution in disguise** ("users need a better search"), a **vagueness** ("the UX is bad," "the process is inefficient"), a **business outcome posing as a problem** ("we need to increase revenue"), or a **symptom mistaken for the cause** (churn is up → "fix churn"). Each one locks the team into solving the wrong thing, well. A good problem statement is a *gap a real user experiences, in context, grounded in evidence, measurable, and free of any named solution*. So this skill gates:

1. **Establish what you actually have** — a validated problem, or a prompt / signal / request / metric that only looks like one.
2. **Apply the always-true core** — separate problem from solution/symptom/goal, find the true cause, make it specific and measurable, ground it in evidence, bridge user and business.
3. **Surface the context-dependent decisions** (which definition tool, how much measurability now, reasoned vs. evidence-validated cause, scope) with trade-offs.

Then it **hands off to `pm-okr-metric-validity-audit` (the measurable element) and `pm-assumption-rigor-audit` (the assumed root cause)** for validation.

Scope: this skill owns the **problem-statement artifact**. It defers the broader **problem-finding process** to `pm-discovery`, **hypothesis/experiment design** to `pm-assumption-testing`, turning the statement into a full **spec** to `pm-product-spec` (audited by `pm-spec-quality-audit`), **ranking which problem to tackle** to `pm-prioritization-rigor-audit` / `pm-prioritization`, **personas depth** to `pm-personas-jtbd`, and **user stories** to `pm-user-story`.

# User Story Skill

## How this skill behaves (read first)

This is a **generative** skill, and user stories are where requirements quietly turn back into a task list. The default move is to restate a feature as a story — "Add login feature," or the hollow "As a user, I want a button so I can submit" — describing *what to build* instead of *who needs what and why*. A real user story is **a small, testable unit of user value, grounded in a real persona's need**, that gives the team a shared who/what/why — and the discipline to *not* write one when it adds nothing the spec already says. So this skill gates:

1. **Establish whose need this is, whether it's real, and what the story feeds** — a story with no grounded user is an assumption in costume.
2. **Apply the always-true core** — frame from user value, keep the story small with detail pushed to acceptance criteria, make it INVEST/testable, map stories across the journey, and cut stories that add no clarity.
3. **Surface the context-dependent decisions** (strict formula vs. free-form, write-a-story-at-all, acceptance-criteria depth, splitting into a map, communication framing) with trade-offs.

Then it **hands off to `pm-spec-quality-audit`** (which flags task-stories, untestable stories, and broken traceability) and **`pm-assumption-rigor-audit`** (is the user need evidenced or assumed?).

Scope: this skill owns the **user-story artifact**. It defers **building the persona** to `pm-personas-jtbd`, **framing the underlying problem** to `pm-problem-statement`, and the **full spec/PRD and acceptance-criteria depth** to `pm-product-spec` (audited by `pm-spec-quality-audit`). **Agile ceremonies, backlog grooming, and sprint mechanics** are out of scope.

# Product Analytics Skill

## How this skill behaves (read first)

This is a **generative** process skill (it plans or performs an analysis, and can critique one). Analytics is where an AI assistant produces confident, wrong conclusions: Claude reports **vanity metrics** (page views, total signups), treats **correlation as causation**, reacts to a **two-day spike** or an **n=20 sample** as if it were a trend, quotes the **average** (which hides every interesting subgroup), and stops at "here are the numbers" instead of a decision. A dashboard nobody acts on, or an insight built on a bias, is worse than no analysis.

So this skill gates:

1. **Establish context** — the decision/question this informs, the goal it ladders to, and the data available (these set what to measure and which method).
2. **Apply the always-true core** — question first, actionable metrics, signal vs. noise, segment, quant+qual, end in a recommendation.
3. **Surface the context-dependent decisions** (analysis method, leading vs. lagging, tooling, attribution model, cohort type, retention window) with trade-offs; let the user choose.

Then it **hands off to `pm-okr-metric-validity-audit`** (are the chosen metrics valid, not vanity?) and **`pm-assumption-rigor-audit`** (do the causal claims and read-outs survive scrutiny?).

# Assumption Testing Skill

## How this skill behaves (read first)

This is a **generative** skill, and "validate our idea" is a default trap. The instinctive move is to jump to a method — build an MVP, run a survey, ship an A/B test — or to test *the idea* ("do you like this?", which everyone says yes to) instead of the **assumptions the idea depends on**. The other failure is investment mismatch: writing code to answer a question a one-day test would settle, or betting the quarter on a hallway poll. So this skill gates:

1. **Establish the decision and its stakes** — what choice does this inform, and how reversible/expensive is it? That sets how much rigor is warranted.
2. **Apply the always-true core** — decompose into testable assumptions, prioritize the riskiest, phrase them falsifiably, set success criteria up front.
3. **Choose the method deliberately** — surface the fidelity/method decision with trade-offs; don't default to "build it and see."

Then it **hands the plan to `pm-assumption-rigor-audit`** to validate (and `pm-okr-metric-validity-audit` for the success metric). **Applying every test type to every assumption is the failure mode** — match one good method to each risky belief.

---

# Product Discovery Skill

## How this skill behaves (read first)

This is a **generative** skill, and "do some discovery" hides several default traps. The instinctive moves are: treat discovery as a one-time research phase before building (then never revisit it), jump straight to solutions and features, run a generic "interview a few users + send a survey" plan without matching the rigor to what's actually at stake, measure success by what shipped rather than what changed, and ask users "would you use this?" (everyone says yes). The result is a feature factory that's busy but not learning. Good discovery is **continuous, problem-first, outcome-oriented, and evidence-matched-to-risk**. So this skill gates:

1. **Establish which risk you're de-risking and how much certainty the decision needs** — value, usability, feasibility, or business-viability risk; a cheap reversible call needs far less evidence than an expensive irreversible bet.
2. **Apply the always-true core** — continuous cadence, outcomes over output, problem before solution, past behavior over hypotheticals, evidence matched to risk, solutions from validated problems, ethical research.
3. **Surface the context-dependent decisions** (problem vs. solution research, qual vs. quant, lightweight vs. deep, DIY vs. specialist, how much certainty before committing) with trade-offs.

Then it **hands off to `pm-assumption-rigor-audit`, `pm-okr-metric-validity-audit`, and `pm-prioritization-rigor-audit`** for validation. The actual **test/experiment design** for a specific assumption belongs to the generative `pm-assumption-testing` skill — discovery decides *what to learn and how much it matters*; assumption-testing designs the *test*.

---

# A/B Testing & Experimentation Skill

## How this skill behaves (read first)

This is a **generative** skill (it designs or revises an experiment plan, and can review an existing test setup). Experimentation is where an AI assistant's defaults are quietly wrong in ways that produce confident, false conclusions. Claude will happily "set up an A/B test" that **declares a winner on a handful of users**, **peeks and stops the moment p < 0.05**, **optimizes one metric with no guardrail** for the damage it does elsewhere, runs for three weekdays, and ends at "B won" with no segments, no long-term read, and nothing written down. A bad experiment is worse than none — it launders a guess into "data."

So this skill gates, and the gate is statistical discipline:

1. **Establish context** — is a controlled experiment even the right tool here, what single decision it informs, and the risk level (these set confidence, split, and duration).
2. **Apply the always-true core** — pre-register the hypothesis and success criteria, size the test *before* running it, run a full cycle, use one primary metric + guardrails, interpret past "it won," and close the learning loop.
3. **Surface the context-dependent decisions** (confidence threshold, traffic split, A/B vs. multivariate, metric type, leading/long-term indicators, test prioritization) with trade-offs; let the user choose.

Then it **hands off to `pm-okr-metric-validity-audit`** (are the chosen metrics valid, not vanity?) and **`pm-assumption-rigor-audit`** (is the hypothesis the riskiest, falsifiable, pre-committed?).

# Prioritization Skill

## How this skill behaves (read first)

This is a **generative** skill, and prioritization is where good intentions turn into a feature factory. Claude's defaults are the failure modes: reach for **RICE for everything** (the wrong tool for a brand-new product, where reach scores near zero), produce **scores that look objective but rest on guesses**, **rank without tracing to strategy** (so the loudest stakeholder wins), treat the **backlog as a dump**, and pretend you can optimize **time, scope, and quality at once**. Strong prioritization is the opposite: criteria derived from strategy, the *right* framework for the situation, scoring used to *surface trade-offs* rather than fake precision, sequencing that protects flow, and a defensible "no." So this skill gates:

1. **Establish the strategy, the stage/constraints, and the decision's reversibility** — these determine the criteria, the framework, and how much rigor is warranted.
2. **Apply the always-true core** — derive criteria from strategy, treat the backlog as a funnel, score to expose trade-offs, balance value × business × feasibility, make trade-offs explicit, sequence don't just rank, say no with context.
3. **Surface the context-dependent decisions** (which framework, scoring rigor, roadmap horizon, appetite vs. estimate, bets vs. tactical) with trade-offs.

Then it **hands off to `pm-prioritization-rigor-audit`** (its primary pairing), plus `pm-okr-metric-validity-audit`, `pm-assumption-rigor-audit`, and — for high-stakes irreversible calls — `pm-decision-quality-audit`.

Scope: this skill owns the **prioritization decision and its sequencing**. It defers the **roadmap artifact and its communication** to `pm-roadmap`, the **strategy itself** to `pm-vision-strategy`, **finding/validating the problems** to `pm-discovery` and `pm-problem-statement`, and the **spec** to `pm-product-spec`.

# Idea → Plan (PM Creation Orchestrator) Skill

## How this skill behaves (read first)

This is the **front door for taking a raw idea to a build-ready plan**, and the PM twin of
`ux-design-from-scratch`. Where `pm-product-review` orchestrates the *validation* direction
(generative → audit), this skill orchestrates the *compositional* direction
(generative → generative): it sequences the PM scope ladder —
**problem → discovery → users → riskiest-assumption test → prioritization → spec → metrics** —
pulling in each skill as the work needs it, then hands the result to `pm-product-review` for
validation.

It is the executable form of the **compositional orchestration** section (§9) of
`docs/orchestration-policy.md`, applied to PM. Its whole job is to avoid the failure this skill

# Product Review (PM Orchestrator) Skill

## How this skill behaves (read first)

This is the **front door for holistic PM-artifact review**. It is the executable form of
`docs/orchestration-policy.md` applied to PM work: it routes by **artifact type** to the
relevant audits rather than firing all of them, auto-runs the one always-relevant lens
(assumption rigor), and returns **one** prioritized report.

PM work has no "design system" suppression case, but it has the same two failures to avoid:
a vague "looks good" review, and forcing every PM audit onto a document that only needs one.

**When NOT to use this skill:** if the user named a specific audit ("run spec-quality",
"check my OKR metric validity"), skip this orchestrator and invoke that one directly.

# Accessibility Audit Skill


## How this skill behaves (read first)

This is an **evaluative** skill — it reviews existing work against a standard (WCAG), it doesn't generate UI. Flagging is safe, so it **auto-runs** and is designed to be **called as a validation step** by generative skills as well as invoked directly.

It **owns the accessibility concern** in this repo. Generative skills hand off to it (e.g. `ux-login-signup`, `ux-pricing`), and the **heuristics audit** (`ux-heuristics-audit`) deliberately defers contrast / keyboard / screen-reader specifics here rather than duplicating them. When invoked, do the full a11y pass; don't assume another skill covered it.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (`ux-design-review`) or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **Tier B — offered (and narrowed to usage when a design system is in play)**. Explicit scope always wins.

---

## What this skill changes vs. default behavior

# Visual Aesthetics Audit Skill


## How this skill behaves (read first)

This is an **evaluative** skill — it reviews existing work, it doesn't generate. It auto-runs and is built to be **called as a validation step** by generative skills. It's the **visual-quality backbone** of the repo: generators that produce UI (`pricing`, `login-signup`, `dashboard`, `onboarding`, component skills) hand off here to confirm they didn't tip into clutter or break hierarchy.

It owns **visual composition**. Two deliberate deferrals so it doesn't duplicate:

- **Color-contrast ratios, and any accessibility concern** (keyboard, screen readers, alt text) → the **accessibility audit**. This skill judges *visual* contrast/emphasis and harmony, not WCAG ratios.
- **Usability, flow, and interaction logic** → the **heuristics audit**. This skill judges how it *looks*, not how it *works*.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (`ux-design-review`) or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **Tier B — offered (and suppressed when a design system already defines visual harmony)**. Explicit scope always wins.

# Dark Patterns Audit Skill


## How this skill behaves (read first)

This is an **evaluative** skill — it reviews existing work, auto-runs, and is built to be **called as a validation step** by generative skills, especially ones touching **conversion, pricing, sign-up, subscription, or cancellation** (`pricing`, `login-signup`, `checkout-payment`, `onboarding`, `offboarding`). It's the systematic version of the ethics guardrail those skills carry inline.

It owns **intent to deceive/manipulate**. Deliberate deferrals so it doesn't duplicate:

- **Honest usability problems** (a confusing-but-not-deliberate layout, unclear label) → the **heuristics audit**. A UX *mistake* is not a dark pattern.
- **Visual clutter / overdesign** → the **aesthetics audit**.
- **Accessibility** → the **accessibility audit**.

The line is **intent**: this audit asks whether the design exploits the gap between *what users think they're doing* and *what the product actually does*.

# Usability Heuristics Audit Skill


## What this skill changes vs. default behavior

Without this skill, a usability review tends to produce a flat list of generic suggestions ("make it cleaner", "improve the CTA") with no framework, no severity, and no link to *why* something is a problem. This skill forces four things:

1. **Every finding names the heuristic it violates** — not a vague opinion.
2. **Every finding gets a severity rating** based on frequency × impact × persistence — so the list is prioritized, not equal-weighted.
3. **Every finding has a concrete, specific fix** — not "consider improving."
4. **The audit resists over-flagging.** Heuristics are principles, not a checklist to max out. A finding only earns a place if it plausibly costs a real user time, confidence, or task completion.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (`ux-design-review`) or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **Tier A — always-relevant, auto-runs**. Explicit scope always wins.

# Information Architecture Audit Skill

## What this skill changes vs. default behavior

By default, Claude critiques a structure by eyeballing the category names — it rarely tests whether the *organization scheme* matches how users actually seek, whether labels carry information scent before the click, whether the hierarchy's breadth/depth ratio forces click-tunneling, or whether users landing mid-site can orient at all. This audit forces four things: every finding names the violated IA principle; labels are tested for scent ("could a user predict the destination?"), consistency, and vocabulary fit; the structure is checked against the seeking modes it must serve, not just the browse-from-homepage path; and findings come severity-rated with concrete fixes — including which research method (card sort, search-log analysis, free listing) would settle a contested call.

This is an **evaluative** skill: it auto-runs whenever a sitemap, navigation structure, category system, or multi-screen flow is being reviewed — and as a validation step after generative skills that structure content (`ux-navigation`, `ux-menus`, `ux-search`).

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (`ux-design-review`) or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **Tier B — offered**. Explicit scope always wins.

---

## The framework — what to check and what a violation looks like

# Microcopy Audit Skill


## How this skill behaves (read first)

This is an **evaluative** skill — it reviews existing copy, auto-runs, and is built to be **called as a validation step** by generative skills (the `ux-microcopy` writer, plus `typography`, `dashboard`, `onboarding`, and component skills hand off here for their labels and messages).

It owns **copy quality**. Deliberate deferrals:

- **Manipulative copy** (confirmshaming, fake urgency, guilt) → the **dark-patterns audit** owns intent; flag and route.
- **Copy accessibility specifics** (alt text rules, screen-reader behavior) → the **accessibility audit**; this skill flags plain-language/clarity, defers the technical a11y mechanics.

**Scope discipline.** When invoked directly (the user named this audit), review **only this concern** — don't pull in sibling audits. It runs alongside other lenses only when an orchestrator (`ux-design-review`) or a generative skill calls it under `docs/orchestration-policy.md`, where it sits in **Tier A — always-relevant, auto-runs**. Explicit scope always wins.

# Mobile Responsiveness Audit Skill

## How this skill behaves (read first)

This is an **evaluative** skill — it reviews existing work against mobile/touch standards, it doesn't generate. Flagging is safe, so it **auto-runs** and is built to be **called as a validation step** by generative skills whenever the target is mobile or responsive (the component family, screens, and flows all hand off here for their mobile context).

It **owns the mobile/touch-adaptation concern** in this repo. To avoid duplicating its sibling audits, it defers:

- **WCAG ratios, screen-reader/assistive-tech, keyboard operability, alt text, captions** → the **accessibility audit**. This skill judges *physical touch ergonomics and layout adaptation*, not AT compatibility or contrast math.
- **Visual composition** — hierarchy, spacing aesthetics, emphasis → the **aesthetics audit**.
- **Usability, flow, and interaction logic** → the **heuristics audit**.
- **Content structure / navigation scheme** → the **information-architecture audit**; **type scale** → `ux-typography`.

> **Applicability gate:** this audit only applies when the target is meant to work on mobile or across breakpoints. If a design is explicitly desktop-only (e.g. a complex internal admin tool with no mobile support), say so and skip — don't manufacture mobile findings.

# Buttons Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes are opposite: **flat sameness** (every action gets the same generic button, no hierarchy, vague "Submit/OK" labels, missing states) and **decoration overload** (every button raised, shadowed, branded, icon-stuffed). A checklist is not a mandate, so this skill gates:

1. **Establish context** — platform, the screen's action hierarchy, brand personality, and whether any action is destructive.
2. **Apply the always-true core** — hierarchy-driven type selection, action-verb labels, full state coverage, accessible sizing and contrast.
3. **Surface the stylistic levers** (shape, elevation, icon-only, FAB, width strategy) as decisions with trade-offs — not defaults.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Cards Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **card stuffing** (multiple topics, long text, every detail crammed into one card), **shadow soup** (shadows on the card *and* its image *and* its buttons), and **cards-for-everything** (card grids where users need ranked, comparable results). A card is *one digestible topic in one container, inviting exploration* — and card layouts fit browsing, not searching. This skill gates:

1. **Establish what's being carded and how users consume it** — browsing vs. searching decides whether cards are even right.
2. **Apply the always-true core** — one topic per card, internal hierarchy, progressive disclosure, restraint.
3. **Surface the container-style and interaction decisions** (elevated/outlined/flat, full-card click, media) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Inputs & Forms Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **over-asking** (every field that might be useful, all required), **mislabeling** (placeholders as labels, jargon, unmarked optionals), and **validating late** (errors dumped in a modal at submit). The fix is not "apply every form pattern" — helper text, tooltips, progress bars, and multi-step splitting everywhere produce a bloated form. So this skill gates:

1. **Establish context** — what the form collects, why each field is needed, platform, and length.
2. **Apply the always-true core** — minimal fields, scannable single-column layout, persistent labels, the right input type per field, inline validation.
3. **Surface the context-dependent decisions** (multi-step, floating labels, helper text, pickers, smart defaults) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, and `ux-dark-patterns-audit`** for validation.

---

# Loaders & Progress Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **one spinner for everything** (a full-page spinner whether the wait is 1 second or 60), **no endpoint when one exists** (indeterminate loops for measurable tasks), and **progress theater** (trackers on 2-step forms, percentages that lie). The feedback type is determined by *wait duration* and *task structure* — and a loader's real job is shaping perceived time, not decorating it. This skill gates:

1. **Establish the wait type** — how long, is it measurable, what initiated it, is it a multi-step journey?
2. **Apply the always-true core** — the duration ladder, placement, state visibility.
3. **Surface the context-dependent decisions** (skeletons, custom animation, tracker labeling, save/autosave) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Menus Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **catch-all dropdowns** (unrelated actions dumped into one menu), **deep ambiguous nesting** (cascading levels users get lost in), and **unordered item lists** (no prioritization, no grouping, jargon labels). A menu is a *curated, ordered set of related actions* — when it stops being that, the fix is changing the flow, not adding levels. This skill gates:

1. **Establish the action set** — what actions, how related, how many, selection or command?
2. **Apply the always-true core** — type from structure, priority ordering, grouping, labels, states.
3. **Surface the context-dependent decisions** (cascading, contextual, search-in-menu, shortcuts) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

> Scope & composition (per `docs/orchestration-policy.md` §9): this skill owns menu *structure and anatomy*. **Peers that own a sub-part (defer — each handles its sub-part if reached):** `ux-navigation` owns where menus live in the overall navigation system (hamburger placement, mega menus, top bar vs. sidebar), and `ux-selection-controls` owns the choice between menus vs. radio/checkboxes for form selection.

# Modals & Dialogs Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **interrupting for everything** (modals for success messages, tips, newsletters — attention spent like it's free), **trapping users** (no visible close, no Esc, stacked modals), and **vague choices** ("Are you sure?" → Yes/No). A modal *takes the whole interface hostage* — that's justified only in high-stakes moments, and the price is paid back with crystal-clear purpose and effortless exit. This skill gates:

1. **Gate the interruption itself** — is a modal even justified here? The most important decision happens before any design.
2. **Apply the always-true core** — purpose in the title, explicit buttons, easy dismissal, focus management.
3. **Surface the type and timing decisions** (popup/fullscreen/popover/bottom sheet, permission priming) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, and `ux-dark-patterns-audit`** for validation.

---

# Navigation Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **pattern-by-habit** (a top bar with a hamburger regardless of IA depth, breadth, or platform), **hidden essentials** (core sections buried behind icons), and **missing wayfinding** (no "you are here" signals, so users dropped in by search are lost). Navigation is chosen by the *structure of the content* and *how users move through it* — not by what modern sites look like. This skill gates:

1. **Establish the IA shape and platform** — these mostly decide the pattern.
2. **Apply the always-true core** — system layering, wayfinding signals, visible essentials, interaction basics.
3. **Surface the pattern decisions** (top bar vs. sidebar, hamburger, mega menu, tabs, breadcrumbs, pagination vs. infinite scroll) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** — and, as a multi-screen structure, to `ux-information-architecture-audit`.

---

# Notifications & Toasts Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **urgency inflation** (everything is an alert; success messages interrupt), **frequency abuse** (repeat pings for the same event until users kill all notifications), and **attention disrespect** (badges for non-notifications, pings with no user value). A notification spends the user's attention — the type must match the message's *actual* urgency, and the system must stay worth listening to. This skill gates:

1. **Establish urgency, audience moment, and channel** — these pick the type.
2. **Apply the always-true core** — type-urgency match, frequency discipline, content brevity, user control.
3. **Surface the engagement levers** (push strategy, personalization, rich media) with trade-offs — this is dark-patterns-adjacent territory.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, and `ux-dark-patterns-audit`** for validation.

---

# Search Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **a box and nothing more** (an input that returns a bare list — no suggestions, no query persistence, no recovery), **dead ends** ("No results found." period), and **feature stacking** (rich suggestions + trending + recent + filters + chips everywhere, even where search is a minor utility). Search is a *journey* — formulate → suggest → results → refine — and which stages need investment depends on how users seek. This skill gates:

1. **Establish how users seek and how central search is** — that decides which stages to invest in.
2. **Apply the always-true core** — discoverable placement, working input conventions, suggestion basics, a scannable results page, no dead ends.
3. **Surface the context-dependent decisions** (rich auto-suggest, filter layout, chips, view options) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Selection Controls Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure mode is **wrong-control selection**: a dropdown for 3 options, a toggle for something that needs a Submit, radio buttons restyled as squares, a slider where precision matters. The control is determined by the *structure of the choice* (how many options, how many selectable, immediate vs. deferred effect) — not by looks. This skill gates:

1. **Establish the choice structure** — that mostly *decides* the control; styling questions come second.
2. **Apply the always-true core** — conventional shapes, interactive labels, clear alignment, defaults.
3. **Surface the context-dependent decisions** (dropdown alternatives, slider variants, preset ranges) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Tables & Lists Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **decoration over data** (heavy borders, zebra everything, centered text, mixed formats), **missing manipulation** (no sorting, no customization — fatal at real data volumes), and **density extremes** (cramped 32px rows or wasteful spacing). A table's only job is letting users *scan, compare, and act on* data — every visual choice either serves that or fights it. This skill gates:

1. **Establish the data shape and tasks** — 2-D comparison (table) vs. 1-D scanning (list), volume, and what users do with rows.
2. **Apply the always-true core** — alignment rules, hierarchy, formats, interaction states.
3. **Surface the context-dependent decisions** (density, pagination type, customization, list variants) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Tooltips Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure modes: **tooltip-as-crutch** (an unclear interface "fixed" by sprinkling hover hints everywhere), **redundancy** ("Submit" button + "Click to submit" tooltip), and **vital info in hover space** (content users *must* see, hidden behind an interaction many will never perform — and that touch devices can't perform reliably). A tooltip is a *supplement for genuinely ambiguous elements* — never a load-bearing part of the flow. This skill gates:

1. **Gate each tooltip's existence** — is the element actually ambiguous, or is the design unclear?
2. **Apply the always-true core** — placement, brevity, styling, cursor signaling.
3. **Surface the escalation decisions** — when a tooltip is the wrong tool entirely.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Checkout & Payment Flow Skill

## How this skill behaves (read first)

This is a **generative** skill. Checkout is the highest-stakes flow in the product — every bit of friction here is paid for in abandoned carts, and the defaults are *leaky*. The instinctive design — force account creation, show one long form, validate only on Submit, drop a blank promo box, surface the final price with no breakdown, and dead-end after payment — bleeds motivated buyers at the last step. This flow is a sequence — **cart → identity → details/address → payment → processing → confirmation** (booking swaps the front for *search availability → select*) — and which stages need investment depends on what's being bought. So this skill gates:

1. **Establish what's being bought and for whom** — that decides the stages, the fields, and the payment mix.
2. **Apply the always-true core** — the conversion-protecting patterns that hold for essentially every transaction.
3. **Surface the context-dependent decisions** (name fields, payment-method count, single- vs. multi-page, booking pickers, promo prominence) with trade-offs.

Then it hands the result to the audit lenses for validation (candidates; posture per `docs/orchestration-policy.md`). **Composition (§9):** checkout composes `ux-inputs-and-forms`, `ux-buttons`, and `ux-selection-controls` as core children, and defers confirmation-modal mechanics to `ux-modals-and-dialogs` and toast behavior to `ux-notifications-and-toasts` (peers — they own those sub-parts if reached). Under an existing design system, inherit color/type/spacing tokens.

---

# Error Recovery Skill

## How this skill behaves (read first)

This is a **generative** skill. Claude's default error handling is the failure mode: it writes "Something went wrong," validates only on submit, blames the user ("You entered an invalid value"), treats every error at the same severity, shouts in ALL CAPS or leaks codes ("Error 403: Forbidden"), offers no way back from a 404, and never thinks about *preventing* the error in the first place. Good error recovery inverts that. Its first move is to **prevent** errors (most are designable away with constraints, masks, and defaults), then make the unavoidable ones **recoverable** — tell the user what happened and what to do next, give them a safety net, and never leave a dead end. So this skill gates:

1. **Establish stakes, error source, and where in the journey the error happens** — these decide how much friction, confirmation, and escalation is warranted.
2. **Apply the always-true core** — prevent first, validate without interrupting, write recoverable messages, give a safety net, never dead-end.
3. **Surface the context-dependent decisions** (confirm vs. undo, validation timing, humor, AI degradation/confidence, transparency vs. security) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, `ux-dark-patterns-audit`, and (when mobile) `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill owns the **error/failure/recovery experience** — error states, message craft, validation behavior, undo/confirmation, degradation, and error pages — and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the recovery experience):** **input-field anatomy** via `ux-inputs-and-forms`. **Peers that own a sub-part (defer):** **toast/notification type & frequency** to `ux-notifications-and-toasts` and **confirmation-modal mechanics** to `ux-modals-and-dialogs` (they own those sub-parts if reached). **Downstream (offer, don't auto-build):** **first-use / no-results / cleared empty screens** via `ux-empty-states`, the **password-reset flow** via `ux-login-signup`, **save-state confirmation** via `ux-settings`, and **help/contact at the point of error** via `ux-contact-support`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Offboarding Skill

## How this skill behaves (read first)

This is a **generative** skill, and offboarding is the single most dark-pattern-prone flow in a product. The business wants to keep the user; the temptation is to bury the cancel link, confirmshame ("No thanks, I don't want to save money"), force a retention gauntlet, or make deletion frictionless to avoid the awkward conversation. Both extremes break trust: hiding the exit is manipulation, and a one-click permanent delete invites catastrophic accidents. Good offboarding holds two truths at once — **leaving must be easy and respectful**, *and* destructive actions must be **deliberate and recoverable**. Done well, a graceful exit preserves goodwill, earns referrals, and leaves the door open for users to return. So this skill gates:

1. **Establish what's being offboarded and how reversible it is** — a subscription cancel (billing, usually reversible) is not an account delete (data loss, often permanent); this sets the right amount of friction and which alternatives to offer.
2. **Apply the always-true core** — findable exit, goodwill over blame, prevent accidental destruction, explain consequences, respectful feedback, genuine alternatives, recovery path.
3. **Surface the context-dependent decisions** (retention incentives, value reminders, confirmation friction, pause-vs-delete) with trade-offs — these are exactly where offboarding tips into a dark pattern.

Then it **hands off to `ux-dark-patterns-audit`, `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, and (when mobile) `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill owns the **leaving experience** — the cancel/delete flow, its copy, retention moments, and recovery — and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the flow):** **the feedback-form fields** via `ux-inputs-and-forms`. **Peers that own a sub-part (defer):** **confirmation-modal mechanics** to `ux-modals-and-dialogs`, the **settings/billing entry point** to `ux-settings`, and the **undo / safety-net pattern** (reactivation, restore window), whose backbone is shared with `ux-error-recovery` (they own those sub-parts if reached). **Downstream (offer, don't auto-build):** **plan-change / downgrade pricing UI** via `ux-pricing`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Onboarding Flow Skill


## How this skill behaves (read first)

This is a **generative** skill, and onboarding is a prime **over-design** trap: the default instinct is a multi-screen tour nobody reads plus a wall of upfront questions and "enable all permissions" prompts — which actively *blocks* the product and drives drop-off. The lessons are blunt: **most apps don't need a tutorial; users learn by using.** So this skill gates hard:

1. **First gate: does this even need onboarding?** Often the answer is "barely" — and the best onboarding is the lightest one that gets users to value.
2. **Apply the always-true core** — the principles that hold for any first-run experience.
3. **Choose the method and asks deliberately** — surface the context-dependent decisions with trade-offs; don't default to a 6-screen carousel.

Then **hand off to the audits** — especially `dark-patterns` (onboarding is where forced permissions/notifications and friend-spam concentrate).

---

# Color Palette & System Skill


## How this skill behaves (read first)

This is a **generative** skill. Color has two opposite default failure modes: **arbitrary** (pick a nice blue, no system, fails contrast) and **garish** (apply every emotional/cultural association and standout trick → the over-colored "Willy Wonka" palette `aesthetics` warns about). So this skill gates:

1. **Establish brand, audience, and market** — these drive the *one* set of hue/emotion/culture choices worth making.
2. **Apply the always-true core** — a restrained, role-based, tokenized, accessible palette holds for any product.
3. **Make the expressive choices deliberately** — surface base-hue/emotion/saturation/dark-mode as gated decisions, not defaults.

Then **hand off to the audits**: `accessibility` owns contrast ratios and color-blindness; `aesthetics` owns harmony and balance.

---

# Iconography Skill

## How this skill behaves (read first)

This is a **generative** foundation skill. Icons are where an AI assistant ships ambiguity: Claude adds **icon-only buttons with no labels**, reaches for **novel or decorative** glyphs instead of the metaphor users already know, **mixes styles** (some outlined, some filled, different stroke weights), and uses **different icons for the same action** across a screen. An icon that makes the user stop and decode it has failed — its whole job is faster recognition.

So this skill gates:

1. **Establish context** — platform/library, whether icons earn their place here, and the design-system maturity (these set the style, the label policy, and the source).
2. **Apply the always-true core** — universal metaphors, one consistent style, labels where meaning isn't obvious, legibility at size, and accessible labels.
3. **Surface the context-dependent decisions** (icon style, system library vs custom, labels, state variants, rendering mode, containers) with trade-offs; let the user choose.

Then it **hands off to `ux-accessibility-audit`** (labels, contrast, touch targets), **`ux-aesthetics-audit`** (style consistency, overdesign), and **`ux-microcopy-audit`** (the icon labels themselves), plus **`ux-mobile-responsiveness-audit`** when touch targets matter.

# Layout, Spacing & Grids Skill

## How this skill behaves (read first)

This is a **generative** foundation skill. Layout is where an AI assistant's output is quietly amateurish: Claude reaches for **arbitrary spacing** (13px here, 27px there), pads things by eyeball, mixes alignments, drops content onto the canvas with **no grid**, and gives every element the same visual weight so nothing reads as more important. The fixes are systematic, not cosmetic — a base unit, a scale, a grid, consistent alignment, and space used deliberately to group and to rank.

So this skill gates:

1. **Establish context** — platform/density, content type, and whether the layout must be responsive (these set the base unit, the grid type, and the column model).
2. **Apply the always-true core** — one base unit and a spacing/sizing scale, align to a grid, let proximity and whitespace group, and use space to build hierarchy.
3. **Surface the context-dependent decisions** (base unit, grid type, column model, sizing approach, golden-ratio/rule-of-thirds, token layer, grid-breaking) with trade-offs; let the user choose.

Then it **hands off to `ux-aesthetics-audit`** (the composition/spacing/hierarchy review) and **`ux-accessibility-audit`** (touch targets, text scaling, reflow), plus **`ux-mobile-responsiveness-audit`** when the layout is responsive/mobile.

# UX Microcopy Skill


## How this skill behaves (read first)

This is a **generative** skill. Claude's default UX copy tends to be **verbose, clever, or generic** ("Oops! Something went wrong", "Submit", "Are you sure?"). Good microcopy is the opposite: plain, specific, and quietly helpful. The expressive part — *tone* — is context-dependent, so this skill gates:

1. **Establish voice, audience, and the moment** — tone that's right for a celebratory success state is wrong for a payment error.
2. **Apply the always-true core** — clarity, concision, action-orientation, consistency, and inclusive/accessible language hold for all copy.
3. **Choose tone deliberately** — pick the register for the brand and the specific moment; don't default to jokey or to robotic.

Then **hand off to the audits**: the companion `ux-microcopy-audit`, plus `accessibility` (copy that screen readers and all users can follow) and `dark-patterns` (copy must persuade honestly, never manipulate).

---

# Typography Skill


## How this skill behaves (read first)

This is a **generative** skill. Typography has two default failure modes: **bland** (pick one safe font, no real scale or hierarchy) and **over-expressive** (multiple display faces, many weights/colors/cases stacked → cluttered and illegible). So this skill gates:

1. **Establish brand personality, content types, and medium** — these drive the *expressive* choices worth making.
2. **Apply the always-true core** — legibility, a clear scale/hierarchy, and restraint hold for any product.
3. **Make the typeface/pairing/scale choices deliberately** — surface them as gated decisions tied to brand, not defaults.

Then **hand off to the audits**: `accessibility` (size, contrast, spacing), `aesthetics` (hierarchy, balance).

---

# Activity Feed Skill

## How this skill behaves (read first)

This is a **generative** skill. A feed's job is to surface what matters and let the noise fade — and the defaults work against that: each entry crammed with every available field, loud exact timestamps, every social control on every row, ungrouped notifications buzzing one-by-one, and a blank feed greeting brand-new users in the exact window where they decide whether to stay. There's also a consequential upfront choice — **chronological vs. algorithmic/ranked** — that teams often make by accident. So this skill gates:

1. **Establish the feed type and what the feed is for** — chronological vs. ranked is hard to change later and reshapes everything downstream.
2. **Apply the always-true core** — curate each entry, keep text legible, downplay timestamps, never show an empty feed, show refresh status.
3. **Surface the context-dependent decisions** (notification aggregation, follow recommendations, per-entry controls) with trade-offs.

Then it **hands off to `ux-aesthetics-audit`, `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-microcopy-audit`, `ux-dark-patterns-audit`, and `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill covers the **feed screen and its entries** and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the feed):** per-entry **card anatomy** via `ux-cards`. **Peers that own a sub-part (defer):** **notification component** behavior to `ux-notifications-and-toasts` and **loaders/skeletons** to `ux-loaders-and-progress` (they own those sub-parts if reached). **Downstream (offer, don't auto-build):** the **empty-feed screen** craft via `ux-empty-states`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Contact & Support Skill

## How this skill behaves (read first)

This is a **generative** skill, and it starts from an uncomfortable fact: **~64% of support contacts are caused by a UX failure** — missing/unclear info, a service problem, a roadblock, or a task that looks too complex. So the default instinct ("add a contact form") treats the symptom. The skill's first move is to *reduce the need* with self-service, then make getting a human easy and predictable when it's genuinely warranted. The common failures: no FAQ/help before the form, a "Contact us" button that drops users into a surprise channel, no wait-time or expectations set, a bot that doesn't admit it's a bot, no help offered at the moment of error, and feedback requests that interrupt and pressure. So this skill gates:

1. **Establish why users contact support and what the team can sustain** — that orders the channels and sizes the self-service investment.
2. **Apply the always-true core** — deflect with good self-service, make contact easy and predictable, close the loop.
3. **Surface the context-dependent decisions** (which channels and order, chatbot vs. human, help-button placement) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, `ux-dark-patterns-audit`, and `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill covers the **support experience and its surfaces** and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the support surface):** the **contact-form field design** via `ux-inputs-and-forms`. **Peers that own a sub-part (defer):** **help search** to `ux-search` and **tooltip craft** to `ux-tooltips` (they own those sub-parts if reached). **Downstream (offer, don't auto-build):** deeper **error-message/recovery design** via `ux-error-recovery`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Dashboard Skill


## How this skill behaves (read first)

This is a **generative** skill, and dashboards have a signature **over-design** trap: cramming every available metric onto one screen. As the lessons put it — *"when everything is important, nothing is."* The default instinct is to show all the data; a good dashboard shows the *few* things that answer the user's question. So this skill gates:

1. **Establish who's looking and what decision they're making** — that determines what belongs on the screen.
2. **Apply the always-true core** — organization, hierarchy, and chart-fit principles that hold for any dashboard.
3. **Decide density, detail, and chart types deliberately** — surface the context-dependent choices instead of defaulting to "show it all."

Then **hand off to the audits** — especially `aesthetics` (clutter/hierarchy is the make-or-break here).

---

# Empty States Skill

## How this skill behaves (read first)

This is a **generative** skill. The default failure mode is the **dead screen**: "No tasks found." — a blank dead-end at exactly the moment a user is newest, most confused, or most blocked. Every empty state is secretly one of the product's highest-leverage screens: it's onboarding (first use), reassurance (cleared), or recovery (no results / 404). The opposite failure exists too — an "empty" screen so stuffed with text, illustration, and three CTAs that it's no longer calm. This skill gates:

1. **Establish why the screen is empty** — the cause picks the pattern.
2. **Apply the always-true core** — explain + guide, never blame, stay calm.
3. **Surface the embellishment decisions** (illustration, CTAs, humor) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, and `ux-microcopy-audit`** for validation.

---

# Landing Page Skill

## How this skill behaves (read first)

This is a **generative** skill, and a landing page has exactly **one job**: move the visitor toward a single conversion goal. The default failure is the **everything page** — full site nav, several competing offers, a vague headline, walls of copy, and a CTA you have to scroll to find — so attention scatters and nobody converts. (Users form a first impression in ~0.05s and read as little as ~20% of the copy.) The opposite failure is a beautiful hero with no value proposition and no reason to trust it. So this skill gates:

1. **Establish the single conversion goal and who's arriving** — that decides what stays on the page and what gets cut.
2. **Apply the always-true core** — one focus, a sharp headline, an obvious value proposition, a prominent CTA, trust signals, fast and responsive.
3. **Surface the context-dependent decisions** (cut vs. keep nav, perks, chat, scroll length) with trade-offs.

Then it **hands off to `ux-aesthetics-audit`, `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-microcopy-audit`, `ux-dark-patterns-audit`, and `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill covers the **landing page itself** and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the page):** **CTA button mechanics** via `ux-buttons`. **Downstream (offer, don't auto-build):** **pricing tables** via `ux-pricing` and the **post-click sign-up/checkout** via `ux-login-signup` and `ux-checkout-payment`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Login & Sign-up Screen Skill


## How this skill behaves (read first)

This is a **generative** skill, so it does **not** blindly apply every best practice — login/sign-up has a set of context-dependent levers (social login, "stay logged in", username vs. email, 2FA) where applying everything is wrong for some products and right for others. Auto-applying all of them produces a bloated, insecure, or privacy-hostile screen.

So the skill works in three moves:

1. **Establish context** (one quick question if it's not already known).
2. **Apply the always-true core** — the patterns that are correct for essentially every auth screen.
3. **Surface the context-dependent decisions** with their trade-offs and a recommendation, and let the user choose — don't silently pick.

Then it **hands the result to the audit skills** for validation: call the **heuristics audit** (`ux-heuristics-audit`) and the **accessibility audit** (`ux-accessibility-audit`) on the generated screen. This skill deliberately does *not* re-derive contrast/keyboard/screen-reader rules — that's the accessibility skill's job.

# Pricing Page Skill


## How this skill behaves (read first)

This is a **generative** skill, and pricing is the textbook case for **gating** rather than applying every best practice. The lessons offer many ways to make a pricing page stand out — badges, per-tier graphics, interactive sliders, charm pricing, anchoring, social proof. Apply them all at once and you get an overdesigned, cluttered, psychologically overwhelming page that *hurts* conversion and trust. So:

1. **Establish context** (Step 0) — pricing decisions hinge on it more than almost any other screen.
2. **Apply the always-true core** — the patterns correct for essentially every pricing page.
3. **Surface the context-dependent decisions** as a *menu* — present each with its trade-off and a recommendation, and let the user pick the few that fit. Stacking many of them is the failure mode.

Then **hand the result to the audit skills** to validate it didn't tip into clutter or dark patterns.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill owns the **pricing page itself** and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the page):** `ux-cards` (tier-card mechanics — shadows, padding, clickable card) and `ux-buttons` (the CTAs). **Downstream (offer, don't auto-build):** the post-click `ux-checkout-payment`. **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Settings Skill

## How this skill behaves (read first)

This is a **generative** skill. Settings is a pattern users know — the job is *get in, change one thing, get out* — and the default failures fight that: a flat dump of every option, the page used as a junk drawer for links that fit nowhere else, technical-jargon labels, no current status shown, destructive actions sitting up top where they're hit by accident, and changes that save with no feedback (or autosave where the user expected a deliberate Save). A settings screen has two design problems in one — **how the options are organized** and **how changes are saved** — and each has its own rules. So this skill gates:

1. **Establish scale, platform, and sensitivity** — how many settings, mobile vs. web, and whether sensitive data is involved decide the structure and the save model.
2. **Apply the always-true core** — relevance, grouping, plain labels, visible status, destructive-last, clear save feedback.
3. **Surface the context-dependent decisions** (autosave vs. Save button, search, advanced split, confirmation/2FA) with trade-offs.

Then it **hands off to `ux-heuristics-audit`, `ux-accessibility-audit`, `ux-aesthetics-audit`, `ux-microcopy-audit`, `ux-information-architecture-audit`, `ux-dark-patterns-audit`, and `ux-mobile-responsiveness-audit`** for validation.

Scope & composition (per `docs/orchestration-policy.md` §9): this skill covers the **settings page and its save model** and composes lower-scope skills rather than re-deriving them. **Core children (built as part of the page):** the **choice of control** (toggle vs. checkbox vs. radio vs. slider) via `ux-selection-controls`. **Peers that own a sub-part (defer):** the **search input itself** to `ux-search` and **notification-preference depth** to `ux-notifications-and-toasts` (they own those sub-parts if reached). **Inherit, don't regenerate:** under an existing design system, take color/type/spacing from its tokens — only set those when designing from scratch.

# Design From Scratch (UX Creation Orchestrator) Skill

## How this skill behaves (read first)

This is the **front door for building a new design from zero**, and the generative twin of
`ux-design-review`. Where design-review orchestrates the *validation* direction
(generative → audit), this skill orchestrates the *compositional* direction
(generative → generative): it sequences the **scope ladder** — foundations → components →
screens → flows — pulling in each lower-scope skill as the work needs it, then hands the result
to design-review for validation.

It is the executable form of the **compositional orchestration** section of
`docs/orchestration-policy.md`. Its whole job is to avoid two failures: building a single screen
with no system underneath it, and over-building everything (all foundations, all 12 components)

# Design Review (UX Orchestrator) Skill

## How this skill behaves (read first)

This is the **front door for holistic UX review**. It is the executable form of
`docs/orchestration-policy.md` — it decides *which* audit lenses run, which are offered, and
which are suppressed, then returns **one** prioritized report instead of a pile of separate
audits.

Its whole job is to avoid two opposite failures: doing a flat "looks good" review with no
framework, and firing every audit in the repo regardless of relevance (the bandwagon).

**When NOT to use this skill:** if the user named a specific lens ("run the accessibility
audit", "check this for dark patterns"), skip this orchestrator and invoke that one skill