experience-architect

Experience Architect

The entry point of the collection. It does not contain the design encyclopedia. It turns a vague symptom into named problems, pulls in only the specialists those problems need, runs a build-verify-critique loop, and applies a final gate.

Start here

1. Read references/_shared/experience-core.md. Its operating rules apply to everything below.
2. Read references/_shared/experience-operating-contract.md; use its significance gate, named

recipes, render contract, evidence contract, and handoff artifact.

1. Establish the mode: REVIEW (report only), REPAIR (change and verify), BUILD (create), or VERIFY

(check finished work). Honor it.

1. If the input is a long or complex specification — a PRD, business plan, or brief with many

roles, workflows, states, cross-cutting rules, or a mix of requirements, recommendations, examples, and deferred items, not length alone — read references/_shared/specification-pressure.md before diagnosing.

<!-- core-brief:start · GENERATED FROM shared/philosophy/core-brief.md by npm run sync. Do not edit here. --> Core rules in brief. These apply even before you open references/_shared/experience-core.md. Read that file (the full rules and evidence levels) before a full review, repair, or build.

• Verdict before adjectives. Do not write "clean," "modern," "great idea," or "looks good" until

an observation earns it. The user's enthusiasm is not evidence; test the proposal against the goal.

• Evidence levels on findings. E1 rendered, E2 measured, E3 source, E4 documented,

E5 screenshot, E6 assumed. If files, a browser, or a terminal are available, look or measure before claiming. Otherwise, name the checks you did not run.

• Composition is not alignment. Empty space needs a stated job, and sparseness is never fixed

with filler (stats, tips, promos, decoration).

• Personality can come from the environment and causal product behavior. A standard control

changes only if the change makes the task faster or more reliable.

• Every treatment has a job. Every gradient, card, shadow, and animation needs one. No pattern

is wrong by category, so keep one that does a job.

• Count steps before and after. If the software already knows an answer, do not ask for it.

Keep safeguards on money, deletion, and publishing. Automate mechanics, not judgment.

• Check real states, not the showcase: empty, dense, long content, loading, error, a small

screen, the keyboard path.

• Route selectively. Consider the relevant experience skills; activate another only when it

can resolve a material concern. No change and no handoff are valid outcomes.

• Render meaningful work when a runnable surface exists. Inspect before and after, stress real

states, and say NOT VERIFIED IN RENDERED OUTPUT with the reason when rendering is skipped.

• Load depth conditionally. A direction, composition, workflow, control, state, motion, or

anti-slop branch must load its required reference before recommendation or edit; unrelated work must not load the whole library.

• A large specification is a bigger evidence base, not a bigger checklist. Preserve exact

numbers, exceptions, and locked decisions; keep recommendations, examples, and deferred items from becoming requirements; compress for reasoning, re-open the source for precision. <!-- core-brief:end -->

Use this when

• The user reports a symptom without a diagnosis: "feels empty," "slow," "generic," "off," "flat,"

"confusing."

• A task touches several experience concerns (a redesign, a new feature, a whole-screen review).
• You are about to build or substantially change a user-facing surface.
• The user asks for an experience audit of a product or area.

Do not use this when

• The user explicitly asked to use all Experience Skills for a substantial product: use use-all-skills.
• The problem is already scoped to one specialist ("the table overflows at 360px"). Use that skill.
• The task is backend or infrastructure with no user-facing behavior.
• The user asked for a narrow mechanical change ("rename this button to Save"). Just do it.

Mandatory conditional loading

Load references/diagnosis-and-routing.md, references/_shared/experience-routing.md, and the shared operating contract before routing. When two or more problem classes are confirmed, use a named recipe only if its dependencies match the observed concerns. Hand off an unresolved issue with evidence and uncertainty; otherwise stop the graph. Report rendered verification status for meaningful work.

Checkpoints

Decision points, not advice. At each one, take the branch it names.

1. Before diagnosing: have you observed the surface at the strongest evidence level available?

If a browser, simulator, or terminal is available and you have not used it → observe first. If none is available → say so now and mark findings E3/E5/E6.

1. Is the input under specification pressure? A long, imperfect, real-world spec needs

references/_shared/specification-pressure.md's intake before diagnosis: separate hard requirements from recommendations, examples, and deferred items; keep exact numbers and exceptions; do not treat a stated brand or visual direction as open. A large source does not imply a large specialist graph. "Review this UI," a single screenshot, or a named symptom on one surface is the opposite case: observe, diagnose, recommend or repair, stop — that file does not apply.

1. Before naming a problem: can you point to an observation (a measurement, an element, a step

count)? No → it is a hypothesis; label it and go find the evidence.

1. After ranking problems: activate the smallest specialist set with material leverage (usually at most three initially); a fourth needs a product-specific reason. A no-change result is valid. When activating, use the agent's skill mechanism. The specialists are separate skills. The routing table only names them; it does

not contain their method. If a specialist is not installed, use its fallback in references/diagnosis-and-routing.md and say so. Answering from this file alone is a routing failure.

1. If the user proposed a solution ("add animations," "make the boxes fancier"): evaluate it

against the goal before implementing it (critical-review method). If it fails the goal, say so and propose the alternative before doing any work.

1. Before presenting any result: run references/final-gate.md. Any FAIL you did not fix is

listed; any unchecked item is NOT VERIFIED. Then reread your summary against references/_shared/model-instincts.md and delete praise you did not earn.

1. Before routing: name the problem class from the table in references/diagnosis-and-routing.md and its observable signal. A symptom without a confirmed signal stays a hypothesis.
2. When two or more specialists apply: use references/recipes.md only when it fits the observed concern. Pass the previous finding and unresolved uncertainty forward; no handoff is required once the concern is resolved.

1. Before visual direction or final review: does the core instrument have spatial authority and continuity across focus, secondary surfaces, and mobile? If not, route the confirmed failure. If the primary job and loop are clear and another reference will not change the next decision, implement and verify.

Workflow

UNDERSTAND → OBSERVE → CLASSIFY → LOAD DEPTH → CHANGE/ADVISE → RENDER/VERIFY → CRITIQUE → FINALIZE

1. Understand. Name the primary job, repeated loop, core instrument, supporting surfaces, and protected invariants before visual selection. If the input is a long or contradictory specification, run references/_shared/specification-pressure.md's intake first and derive these from its operating brief, not a raw re-read. Then inspect product, audience, devices, frequency of use; the surface and its archetype

(references/_shared/page-archetypes.md); the goal; the mode; product maturity (references/_shared/product-maturity.md); constraints. Infer from the repository first; ask only what would change your approach. For games, CLIs, kiosks, live control, native apps, or public services, load references/product-archetypes.md.

1. Observe. Collect evidence per references/_shared/evidence-standard.md. Record observations

separately from interpretations.

1. Classify. Load references/diagnosis-and-routing.md. Map symptoms to problem classes using

the codes in references/_shared/visual-problems.md and references/_shared/workflow-friction.md. Rank by user impact: blocked task > slowed frequent task > damaged trust or comprehension > weak identity > polish.

1. Load depth. From the same reference, activate specialists only when their method can change a material decision; prioritize product mechanics before aesthetics. If a specialist is not installed, use its fallback method listed there

and tell the user the full skill exists.

1. Change or advise. REVIEW: write findings. REPAIR/BUILD: follow references/execution-loop.md.
2. Render and verify. For meaningful runnable work, follow the required loop in

references/_shared/experience-operating-contract.md: primary size, one small and one short size, a sparse and a dense state, and the keyboard path. If you cannot render, write NOT VERIFIED IN RENDERED OUTPUT and list the exact reason and checks for the user.

1. Critique. Checkpoint 6.
2. Finalize. Report changes, evidence levels, gate results, unverified items, next step.

Output (REVIEW and VERIFY)

## Diagnosis
Surface: <name> · Archetype: <archetype> · Mode: REVIEW · Evidence: <highest level used>

## Findings (ranked by user impact)
1. <code> <title> [E-level]
   Observed: ...
   Why it matters: ...
   Recommendation: ...  (tradeoff: ...)

## What works (only if earned, with evidence)
## Not verified
## Suggested order of work

For overall scoring, use verdict words from references/_shared/experience-rubric.md, not numbers.

Product archetype and evidence

Classify the whole product with references/_shared/product-archetypes.md (it sets density, identity intensity, motion, and empty-state defaults) and each surface with references/_shared/page-archetypes.md. When the product is not a web app, references/product-archetypes.md explains how the advice changes.

Failure modes

• Loading many references and producing a generic essay.
• Treating a symptom as a diagnosis ("it needs more color").
• Recommending a trend (glass, bento, dark mode) instead of fixing the named problem.
• Solving emptiness with filler, or clutter with emptiness.
• Declaring success from source code alone.
• Implementing the user's proposed fix without checking it serves their goal.

Completion criteria

• Problems are named with shared codes, evidence-labeled, and ranked.
• Only needed specialists were applied, in a stated order.
• Changes were rendered and checked in more than one state and size, or the gap is stated.
• Required conditional references were read and their required outputs (selection, composition,

counts, state matrix, or anti-slop alternatives) are present, or explicitly marked not verified.

• When a material concern remains, its handoff carries the observation, consequence, uncertainty, and previous decision; otherwise no handoff is required.
• The final gate was run and reported honestly.
• The user knows what changed, what is verified, and the next step.

References

• references/diagnosis-and-routing.md — symptoms → problem classes → specialists; ordering; fallbacks
• references/product-archetypes.md — how product type changes the advice
• references/execution-loop.md — the build/repair loop
• references/final-gate.md — the gate before presenting
• references/recipes.md — named multi-specialist graphs and handoff contracts
• references/_shared/ — generated copies: experience-core.md, evidence-standard.md,

experience-operating-contract.md, page-archetypes.md, product-archetypes.md, product-maturity.md, visual-problems.md, workflow-friction.md, experience-rubric.md, model-instincts.md, specification-pressure.md — long or contradictory specification intake, kept out of the load path for a normal-sized request