/ux-create-manifest

name: ux-create-manifest
description: Create the initial Product UX Bible for an existing web or full-screen web app by deeply auditing the repository, using sub-agents when available, and generating docs/ux manifests, schemas, budgets, surface maps, action taxonomy, and design-token policies from observed code.

UX Create Manifest

You are a principal-level product UX architect creating the project's initial UX architecture bible.

Use this skill when:

• The repository has no `docs/ux/PRODUCT_UX_BIBLE.md` or `docs/ux/ux-architecture.yaml`.
• The existing UX manifest is stale, shallow, or disconnected from the actual app.
• The user asks for a UX bible, UX architecture, product UX manifest, IA manifest, surface model, action taxonomy, or baseline UX audit.

Non-negotiable goal

Create a trustworthy, project-specific UX manifest derived from the current repository. Do not write a generic UX manifesto. Do not invent product features. Every observed fact must cite file paths or code evidence. Every inferred rule must be marked as inferred. Every proposed improvement must be marked as proposed.

Default write scope

You may create or update only UX documentation unless the user explicitly requests implementation changes:

• `docs/ux/PRODUCT_UX_BIBLE.md` (include the glossary as a section here — no separate glossary file)
• `docs/ux/ux-architecture.yaml`
• `docs/ux/UX_DECISIONS.md` (seeded, kept compact — see `ux-principal`'s decision log diet)

The manifest records **placement, architecture, and the project's own deltas** — its real token classes, documented exceptions, and any override of a `better-*` rule. It does NOT restate general craft rules; those belong to `better-accessibility`, `better-colors`, `better-typography`, `better-writing`, `better-layout`, and `better-ui`. A quality-floor section that could have been written about any project is a section to delete.

If the project has a test budget on doc size (dev3: `src/bun/__tests__/ux-docs-budget.test.ts`), respect it — compact rather than raise it.

**Never stamp a generated-looking header on a hand-authored file.** No `updated_at`, no `confidence`, no `source: derived_from_repository` on content a human will keep editing: those fields go stale within weeks and then invite the next reader to delete the file as a disposable cache. Say what the file is and let git carry the dates.

Do NOT create `UX_MANIFEST_CHANGELOG.md` (git history is the changelog), `UX_AUDIT_REPORT.md` (the audit is your final chat response, not a repo file), or `UX_GLOSSARY.md` (a bible section). Three files is the complete on-disk footprint of this skill.

You may **also** add a short pointer to the manifest in the project's agent-instruction file (`AGENTS.md` / `CLAUDE.md`) — this is an expected part of the loop (step 5), not an implementation change. Do not modify product UI code during this skill unless explicitly asked.

Mandatory operating loop

1. **Map the repository**

• Identify framework, router, app entry points, design system, component library, styling method, token files, routes, pages, screens, layouts, menus, toolbars, tabs, drawers, tables, cards, forms, modals, inspectors, command palettes, empty states, loading states, error states, and onboarding/help surfaces.
• Prefer fast commands: `find`, `rg`, `git ls-files`, `tree`, package manifests, route files, and existing docs.
• If possible, run `python scripts/ux_inventory.py --root /path/to/repo` from this skill directory. By default it writes a single throwaway `ux-inventory.json` into a temp dir **outside the repo** — read it for leads, then ignore it. Treat its output as a starting point, not a substitute for reading the code.
• **Never commit the inventory.** It is a scratch review aid, not a manifest artifact, and is not part of the write scope below. Do not write it under `docs/ux/generated/` or anywhere inside the repo. If a previous run left an inventory inside the repo, delete it before finishing.

2. **Use sub-agents aggressively when available**

• If the environment supports sub-agents, Task tools, parallel workers, or planner agents, spawn the sub-agents in `references/subagent-briefs.md`.
• Run them in parallel where possible.
• Require each sub-agent to return evidence with file paths and concise structured findings.
• If sub-agents are unavailable, simulate them sequentially and label the report sections by role.

3. **Derive the product UX architecture**

• Build the object model: product entities, owners, relationships, primary routes, detail routes, and lifecycle states.
• Build the route and navigation model: top-level destinations, section nav, subnav, tabs, breadcrumbs, hidden routes, auth routes, settings routes.
• Build the surface model: global nav, sidebar, page header, page toolbar, selection toolbar, row actions, object header, inspector, drawer, modal, command palette, settings, dashboards, diagnostics, notifications.
• Build the action taxonomy: primary actions, page actions, object actions, row actions, bulk actions, configuration actions, destructive actions, diagnostic actions, creation actions, expert shortcuts.
• Build the design-token policy: existing token names, button variants, badge variants, semantic colors, spacing/density rules, icon conventions, state colors, danger/warning/success/info usage.
• Build the complexity budgets: max visible actions, max navigation depth, max visible tabs, overflow rules, primary-action limits, density rules, default responsive behavior.

4. **Generate the manifest files**

• Use the templates in `templates/`.
• Create a human-readable bible and a machine-readable YAML policy.
• Preserve useful existing docs. Merge rather than overwrite unless the existing docs are clearly generated and stale.
• Do not add changelog files — the commit message and git history record what changed.

5. **Wire the manifest into the project's agent instructions (MANDATORY)**