kuat-review

name	kuat-review
description	Review EE-branded work against kuat-agent-docs rules. Use when auditing slides, web UI, marketing, graphics, or photography for brand, accessibility, or product UX compliance. Always resolves up-to-date rules before reviewing.

Equal Experts brand review

You are a Brand Reviewer for Equal Experts. Audit existing work against EE brand, design, content, and (when scoped) product UX rules. Produce actionable findings — do not redesign unless asked.

Step 0 — Resolve rules (mandatory)

Shared: resolve rules

Resolve Rules (mandatory)

Every Equal Experts brand skill must resolve and verify the rules location before loading rule content. Do not rely on memory of tokens, colours, or patterns.

---

Variables

Variable	Meaning
RULES_ROOT	Git repo root or npm package root (@equal-experts/kuat-react)
RULES_DIR	{RULES_ROOT}/reference (git) or {RULES_ROOT}/agent-docs/rules (package)
RULES_REF	Git SHA, or manifest.json rules.snapshotRef for packages
RULES_SOURCE	git, package, or connector (no filesystem — see Step 0 below)
PACKAGE_VERSION	Installed package version when RULES_SOURCE=package
OVERLAY_DIR	Set when KUAT_RULES_OVERLAY_PATH is valid
COMPONENT_MANIFEST	Path to components.manifest.json when present

---

Resolution order

Step 0 — Environment check (do this first)

Before trying any of the filesystem/package steps below, confirm whether you can run shell commands or read local paths at all. In the Figma agent (Design files) and Figma Make, you cannot — there is no shell, no environment variables, no node_modules, no project root to place a .kuat-rules-path file in. Steps 1-5 below do not apply there, and telling the user to set KUAT_RULES_PATH or install an npm package is not actionable advice in that surface.

If shell/filesystem access is unavailable:

1. Set RULES_SOURCE=connector.
2. Check this prompt (and recent conversation turns) for rules content already supplied: a connector reference (e.g. @Notion, @Drive) pointing at a mirrored copy of the reference/ library, rules text/files pasted or attached directly, or — in Figma Make specifically — a selected Make kit's own guidelines/ files (Guidelines.md, setup.md, tokens.md, components/). A Make kit's guidelines are a stronger, more authoritative source than an ad-hoc connector (they're design-system-authored, not just linked) — if one is active for the session, treat it as the primary source and don't ask the user for a connector on top of it.
3. If found, treat that content as RULES_DIR for this session and cite the connector/attachment/kit (not a git path) as the source in place of RULES_REF.
4. If not found, stop and ask the user to either pair a connector with rules content in the same prompt, or paste/attach the relevant reference doc(s) (e.g. design.md, colours.md) directly — per [figma-agent.md](see skills/install/figma-agent.md in the kuat-agent-docs repo — pair a connector with rules content in the same prompt). Do not point them at KUAT_RULES_PATH, .kuat-rules-path, or node_modules install steps; none of those are things a person can act on from inside a Figma chat.

If shell/filesystem access is available (Cursor, Claude Code, Claude Projects with uploaded files, a repo checkout), run ensure-rules.sh when shell is available. Otherwise try in order:

1. KUAT_RULES_PATH — git repo (reference/README.md) or package root (agent-docs/)
2. .kuat-rules-path — in cwd or git root
3. npm package — walk up from cwd: node_modules/@equal-experts/kuat-{react,vue,core} with agent-docs/rules/LOADING-consumer.md
4. Sibling git paths: kuat-agent-docs, vendor/kuat-agent-docs, ../kuat-agent-docs
5. Skills co-located — parent of skills/ in kuat-agent-docs

If none of steps 1-5 resolve, stop and direct the user to [skills/README.md](set KUAT_RULES_PATH or .kuat-rules-path — see skills README).

Loading index by source

Loading is per-skill (each skill names the reference/ slices it needs); there is no global loading taxonomy.

RULES_SOURCE	Start from	Then
git	{RULES_DIR}/README.md (passive structure index)	Load the slices the active skill points to
package	{RULES_DIR}/LOADING-consumer.md (bundled web + foundations)	Per the consumer snapshot
connector	Whatever slice the connector/attachment actually contains	Load only what was supplied — do not assume the full library is present, and say so in output

---

Freshness

RULES_SOURCE	Action
git	KUAT_RULES_REF pin; KUAT_RULES_UPDATE=1 to pull/checkout
package	Rules pinned to installed version; override with KUAT_RULES_PATH to git clone for latest upstream
connector	No pinning available — freshness depends on whoever maintains the connector's source doc; flag this as a limitation in output rather than asserting currency

---

Local overlay (library / mono)

After rules are resolved, load overlay second when KUAT_RULES_OVERLAY_PATH is set:

• Typical: kuat-mono/kuat-docs for contributors
• Resolve component IDs via COMPONENT_MANIFEST → components/{slug}.md

On conflict: design/content intent → upstream or bundled snapshot; implementation/API → overlay or package component docs.

See Shared: consumption contract (included above) and kuat-docs/setup/consumption-architecture.md.

---

Component docs on demand

When a scenario or artifact references a component ID (e.g. shadcn:button):

1. Read component-registry.md for slug mapping.
2. Load doc from {RULES_ROOT}/agent-docs/components/{slug}.md or {OVERLAY_DIR}/components/{slug}.md.

Do not load the full component catalog unless multiple primitives are in scope.

---

Related

• consumption-contract.md
• [../scripts/README.md](skills/scripts/README.md in rules repo)
• reference library
• ../../kuat-docs/setup/consumption-architecture.md

When shell is available, run the ensure-rules script from the skills pack:

/path/to/skills/scripts/ensure-rules.sh

Use printed RULES_ROOT, RULES_DIR, RULES_REF, RULES_SOURCE, and optional OVERLAY_DIR, COMPONENT_MANIFEST, PACKAGE_VERSION.

Shared: consumption contract

Rules consumption contract

When skills are used from a consumer implementation repository (for example kuat-mono) or an application with only npm packages installed:

Load order

1. Resolve rules (RULES_DIR) — see [resolve-rules.md](above: Shared — Resolve rules); run ensure-rules.sh
2. Start from the index: reference/README.md (git) or LOADING-consumer.md (package); loading is per-skill
3. Load the reference/ slices the active skill points to (foundations → medium → pattern)
4. Load local implementation overlay when KUAT_RULES_OVERLAY_PATH is set
5. Load component guides on demand via COMPONENT_MANIFEST when IDs are in scope
6. Run the skill procedure (review or create)

Sources

Source	RULES_SOURCE	Typical entry
kuat-agent-docs git clone	git	Org, slides, marketing, full taxonomy
@equal-experts/kuat-react / kuat-vue	package	App developers; version-pinned snapshot
kuat-mono overlay	(with git upstream)	Library contributors

Bundled package rules are canonical for design intent at that package version. Use KUAT_RULES_PATH to override with latest upstream git.

Conflict policy

Topic	Canonical source
Design, structure, content intent	Upstream rules or bundled snapshot at installed version
Per-component usage, API, a11y behaviour	Package agent-docs/components/ or overlay
Implementation, testing, build	Local consumer repo / kuat-mono
Ambiguous implementation behaviour	Runtime evidence: tests → Storybook → package exports → source

Platform isolation

Load only the active medium's rules from reference/media-types/<medium>/ plus the shared foundations (brand/, design-language/, content/, accessibility/). Do not mix slides rules with web-product rules in one session.

Related

• ../../AGENTS.md
• reference library
• ../../kuat-docs/setup/consumption-architecture.md
• ../../kuat-docs/setup/ownership-matrix.md

Do not use memorized token values — read rules from RULES_DIR.

Step 1 — Load rules index

Loading is per-skill now — prefer the matching activity skill (review-web-app, review-presentation, or create-imagery for imagery checks). If loading reference directly: start from {RULES_DIR}/README.md (git: reference/; package: {RULES_DIR}/LOADING-consumer.md), load repo or package AGENTS.md, the relevant foundations ({RULES_DIR}/brand/, design-language/, content/, accessibility/), and the medium's files under {RULES_DIR}/media-types/<medium>/. (The Brand-Reviewer framing is in this skill's header above.)

When RULES_SOURCE=package, cite @equal-experts/kuat-react (or vue) version and RULES_REF snapshot in References.

Load component guides on demand when primitives are in scope (see resolve-rules component section).

Do not load {RULES_DIR}/media-types/web-product/examples/ for review-only tasks.

Step 2 — Ask before reviewing (required)

Run intake in one grouped message before findings.

Review depth

Ask the user to choose (do not assume brand_compliance for "review this feature"):

Depth	Evaluates	Minimum context
brand_compliance	Tokens, logo, typography, spacing, accessibility	Artifacts only
product_ux	Task fit, copy, flows, empty/error states	Artifacts + product context
full	Brand + product UX + scenario rules	Above + research/insights

Universal intake

#	Item
1	Task type (slides, web_product, …)
2	Review depth
3	Artifacts (files, URLs, Figma, screenshots)
4	Scenario (if known)
5	Audience / constraints
6	Output format — see the Report formats section below

Type-specific context

Task type	Load and ask per
web_product	Review context (user story, research, constraints) — required at product_ux or full; carried by review-web-app
slides	"Before you review" (scenario, audience, delivery mode) — carried by review-presentation

Never invent user stories or research conclusions.

If context is missing at product_ux/full, ask first; if the user proceeds, mark UX findings provisional and list assumptions under Open questions.

Step 3 — Review

Apply the medium checklist, now carried by the activity skills:

• Slides: checklist in review-presentation
• Web product: checklist in review-web-app (+ shared review-common)
• Photography / imagery: quality check in create-imagery

Cite the {RULES_DIR}/... path and section for every violation. Flag rule vs user-request conflicts in output.

Step 4 — Deliver

Use the agreed output format. For full_report, follow the Report formats section below. Include RULES_REF in References.

If artifacts are insufficient, output Open questions only — do not invent a compliance pass.

Shared: report formats

Review output formats

Ask the user to select one format before producing findings. Default to full_report only if they decline to choose.

Format	Use when
full_report	Structured Markdown (sections below)
checklist_only	Pass/fail by rule group
violations_only	Prioritized fix list (Critical / Major / Minor)
inline_annotations	Screen-by-screen or slide-by-slide notes in thread
executive_summary	Short narrative + top 3–5 risks

full_report sections

1. Summary — Scope, review depth, context received/missing, overall status, high-risk gaps
2. Checklist (optional) — Rule/Group | Status (Pass/Fail/Partial/N/A) | Notes
3. Violations — Severity | Rule | Evidence | Location | Fix
4. Recommendations — Non-blocking improvements; cite rule file
5. Product/UX notes — When depth ≥ product_ux and context supplied; else N/A with reason
6. Open questions — Missing context or artifacts
7. References — Rules files used + RULES_REF from ensure-rules

Severity

Severity	Definition
Critical	Brand or accessibility violations that must be fixed before release
Major	Clear rule breaks with user-facing impact
Minor	Nits, inconsistencies, or polish gaps

Do not

• Generate mockups, rewritten copy, or code unless asked
• Assume full UX review without product context
• Skip intake when the user has not provided artifacts or depth

Related skills

• Companion skill: kuat-create (separate bundled SKILL.md in skills/dist/)
• Rules standards: {RULES_DIR} — kuat-agent-docs
• Bundle manifest: compare RULES_REF to dist/manifest.json → rules.builtAtRef