hyperplexed-audit

name

hyperplexed-audit

description

Audit and polish UI surfaces with the Hyperplexed-derived design playbook. Use when Codex is asked to audit, review, redesign, refine, or implement UI fixes for a component/page/route using Hyperplexed's workflow; when the user invokes or references /hyperplexed-audit; or when BuildOS UI work should cite Hyperplexed P-patterns, update the Hyperplexed audit tracker, or apply the reusable Svelte/Tailwind/Inkprint recipes.

Hyperplexed Audit

Use this skill to run the migrated /hyperplexed-audit flow as a Codex-native skill. The goal is not a broad redesign. Audit one surface, region by region, using the Hyperplexed playbook as the rubric and the P-patterns as the implementation recipes.

Load Context

For BuildOS, prefer live repo docs over bundled references because the tracker and prior audits can change:

• apps/web/docs/technical/components/hyperplexed/HYPERPLEXED_DESIGN_PLAYBOOK.md
• apps/web/docs/technical/components/hyperplexed/HYPERPLEXED_FIX_PATTERNS.md
• apps/web/docs/technical/components/hyperplexed/HYPERPLEXED_AUDIT_TRACKER.md
• apps/web/docs/technical/components/INKPRINT_DESIGN_SYSTEM.md when implementation is likely
• Matching prior audits in apps/web/docs/technical/components/hyperplexed/ and apps/web/docs/technical/audits/

If those repo docs are missing or the task is outside BuildOS, read the bundled equivalents:

• references/playbook.md for the rubric
• references/fix-patterns.md for reusable recipes
• references/audit-tracker.md for tracker shape and backlog model
• references/claude-command.md for the original Claude Code command
• references/audit-examples/ only when an example audit format is needed
• references/transcripts/ only when grounding a new heuristic or effect in the source corpus

Workflow

1. Resolve the target. If the user gives no target, ask for one component, route, page, or file path. For a route, include the +page.svelte and its main children.
2. Search for prior art. Look in the Hyperplexed docs, the general audits folder, and the tracker. If a prior audit exists, stack on it instead of rediscovering the same items.
3. Enumerate regions before judging. Examples: header, sidebar, card list, composer, filter bar, table, footer, modal chrome. Do a static markup pass first; a dev server is optional until visual verification.
4. Audit each region in leverage order:
   • Alignment and geometry
   • Even padding and density
   • Labels and microcopy, trying rename before redesign
   • Hierarchy by type, not extra containers
   • Decluttered paths, filters, drawers, and scroll regions
   • Overflow handling for user-supplied strings
   • Icon consistency, imagery, and scrims
   • Motion, reduced-motion gating, keyboard access, primitives
   • At most one earned signature delight per surface
5. Present findings tiered by leverage and stop before code edits unless the user has already explicitly approved implementation.

Use this report shape:

## Tier 1 - cheap, high-impact (alignment/padding/labels)

- [region] finding -> P#

## Tier 2 - structural within the surface (declutter/hierarchy)

- [region] finding -> P#

## Tier 3 - polish/signature (motion/effects, at most one per surface)

- [region] finding -> P14-P18

Every finding must cite a pattern such as -> P1, -> P6+P1, or -> new P? if no recipe fits.

Applying Fixes

Apply only fixes the user approved in the audit phase. Use the P-recipes directly where they exist:

• P1 overflow-safe rows
• P2 two-radius rule
• P3 shared shell width and padding
• P4 metadata as subtext
• P5 .micro-label
• P6 rename before restyle
• P7 filters button plus selected chips
• P8 do not hide what fits
• P9 fixed icon containers and one icon set
• P10 imagery scrims
• P11 reduced-motion gating
• P12 mobile card fallback for wide tables
• P13 primitives for interactive controls
• P14-P18 signature effects

Respect BuildOS conventions: Inkprint tokens, Svelte 5 runes, Tailwind, light and dark mode, lucide icons through $lib/icons/lucide.ts, and no edits to src/lib/components/ui/ primitives unless the user explicitly asks.

If an approved fix creates a reusable pattern and a second surface will plausibly need it, add the next P-number to HYPERPLEXED_FIX_PATTERNS.md with the same finding/recipe shape, include reduced-motion behavior, and cite it from the audit.

Verification And Docs

After implementation, run the local checks appropriate to the repo. For BuildOS web work, the original flow expects:

cd apps/web && pnpm check
pnpm format

State the results. If fixes are visual, note whether live before/after screenshots were captured at desktop and iPhone widths in light and dark mode. If not captured, mark that as still owed.

Update docs when the surface warrants it:

• Tracker: add or update the row with shipped fixes, deferred items, P-pattern citations, and verify status.
• Audit doc: create or update apps/web/docs/technical/components/hyperplexed/<SURFACE>_AUDIT_<date>.md for multi-region findings or deferred work. Append to an existing audit instead of creating a duplicate.
• Cross-reference broad audits such as DESIGN_AUDIT_2026-06-12.md and MOBILE_EXPERIENCE_AUDIT_2026-06-12.md when findings overlap.