/visionaire:startMost bugs aren't code bugs. They're interactions nobody designed.
Translate your approved Product Brief into user flows, interaction patterns, and interface decisions — before architecture commits to any implementation approach. Experience first. Structure second.
None of this is theoretical. These are the patterns that show up every time.
That's the under-specified interaction category. The one nobody designed, nobody caught in review, and nobody noticed until a user lost something real. A product design consultant reviews every user journey and catches exactly this — before a developer sees the spec.
UX decisions made during implementation are made under time pressure, inside technical constraints, by people solving engineering problems. That gap gets filled — the question is when and by whom.
The UI/UX Phase extracts every experience decision before a single architectural choice constrains it. What you get is a specification concrete enough that no architect has to guess.
The standard isn't aesthetic judgment. It's whether an architect can design the system without guessing at a single UX decision. Ten criteria. All must pass.
Architects who don't have a UX spec make UX decisions. Those decisions get built into data models, API contracts, and component boundaries. Changing them later means rewriting the architecture, not just the UI.
Start my spec session — $297The outline-first pattern catches structural misalignment before prose is written. The pre-outline gap check catches Product Brief misalignment before structure is committed.
The agent reads BRIEF.md and presents a structured comprehension summary anchored on Design Intent: the core problem, target users, primary use cases, success criteria, scope boundaries. The workflow halts. You confirm the agent understood correctly — or correct it before a single design question is asked.
One question at a time across six categories: user journeys, screens and surfaces, interactions and states, accessibility, responsiveness, and performance. The agent adapts based on what needs depth and what's already clear. When you go deep, it follows. When an area is settled, it moves on.
After the interview completes, the agent reviews the Product Brief again with your responses in mind. It checks for gaps: use cases without user journeys, target users without designed workflows, success criteria without UI support, scope items not reflected in navigation. Follow-up questions resolve gaps before outline commitment.
Produces UIUX-outline.md: user journeys, screens, interactions, states, accessibility, responsiveness, performance — plus explicit assumptions and identified gaps. You review before expansion. Corrections cost minutes at this stage. Corrections after full expansion cost hours.
Approved outline expands into UIUX.md: detailed user journeys with failure scenarios, screen specifications with all states documented, interaction patterns with triggers and constraints, accessibility requirements, responsive strategy, and performance constraints. Nothing is left for architects to infer.
An autonomous review agent evaluates UIUX.md against ten criteria: design intent completeness, end-to-end system journey, onboarding and first-use definition, user journey coverage including failure scenarios and recovery paths, screen and surface clarity including all four states, interaction and state definition including error recovery, destructive actions documentation, constraint declaration, success criteria alignment with the Product Brief, and architectural derivability. APPROVED only if all ten pass. REJECTED triggers revision with a specific report on what's missing and why it matters.
UI/UX Design has a formal stage gate. An autonomous review agent evaluates UIUX.md against ten criteria before Architecture can proceed. APPROVED means an architect can design the system without making a single UX assumption. REJECTED means gaps exist — the review report names each one specifically.
The stage gate rejects. The gap check surfaces a workflow you forgot. The phase detects a project that has no interface. Here's how each plays out.
You ran the full interview. You approved the outline. UIUX.md looks thorough. The review agent comes back: REJECTED. "Client approval flow: success state undefined. Audit trail screen: mobile behavior undocumented. Keyboard navigation: declared as required but no detail on tab order for modals." You thought you were done.
The rejection report is a map to exactly what's missing. Three specific gaps, each with a one-line explanation of why an architect needs that answer. You address the three points. The agent revises. Second review: APPROVED. Architecture proceeds without anyone guessing at a single UX decision.
UIUX.md-v2 that passes all ten criteria — a document where every state is named, every constraint declared, every screen's mobile behavior documented before architecture builds anything.
Your Product Brief described admin users who manage the spec library and approve change requests. The interview covered Sarah's workflow in detail. The gap check runs: "BRIEF.md identifies admin users as a distinct role with spec management permissions. No admin workflow appears in the interview responses." You realize you never thought through the admin experience at all.
Four follow-up questions cover the admin interface. The agent confirms the outline now includes both user types. The spec it produces covers Sarah's daily workflow and the admin controls she needs to set up projects and manage permissions. Architecture gets the full picture — not just the primary user's half of it.
A UIUX.md that reflects every user type your Product Brief defined — not just the one you were thinking about during the interview. The gap check exists precisely for this.
You're building a background webhook processor. Your Product Brief describes an API that receives events, validates payloads, and routes them to downstream services. No user-facing interface. No screens. No interaction patterns to specify. You run /visionaire:start and wonder if this is the right move.
The agent reads BRIEF.md. It detects the project has no user-facing interface: no dashboard, no screens, no end-user interaction patterns. It confirms its interpretation with you and routes directly to Architecture Phase. No interview. No wasted time on questions that don't apply. The pipeline adapts to what you're actually building.
Immediate routing to Architecture with a clear note in the pipeline log explaining why UI/UX was bypassed — so the decision is documented, not silently skipped.
Market evidence has been gathered. You know what you're building and that people want it. UI/UX is where "what" becomes "how it feels" — before Architecture makes "how it works" decisions that lock in the experience.
Architecture reads UIUX.md to understand what it's designing a system to support. Every architectural decision — data model design, API contract structure, component boundaries — is made in service of the experience defined here. Without it, those decisions default to engineering convenience.
Teams do it. The tradeoffs are the same every time.
The experience gap between the Product Brief and Architecture gets filled either way. The question is who fills it and when. UX decisions made during implementation are made inside constraint boxes that already exist. UX decisions made in the UI/UX Phase are made before any constraint exists. The quality difference between those two contexts is not marginal.
I built the Product Brief comprehension step into UI/UX after watching architects spend three days reverse-engineering what the product was supposed to feel like — because no one had ever written it down. The stage gate isn't a hurdle. It's the only way to know whether what you wrote is specific enough to build from.
— Robert EvansA UX spec reviewed by a product design consultant — before architecture sees it — catches the missing confirmation dialog, the undefined empty state, the workflow nobody thought to draw. A redesign mid-architecture costs 4–6 weeks. This phase costs an afternoon.