Discovery brief user experience (#2)

Author: kentcdodds

exercises/01.building-an-mvp/02.solution.stakeholder-meeting/discovery-brief.md

@@ -14,8 +14,11 @@ This document now captures clarified answers and decisions before implementation
 
 - 💼 Brett the Business Owner (business goals, viability, scope pressure)
   - Meeting input: prioritize fast learning and completed-plan outcomes
+  - Meeting input: reference competitor UX patterns from when2meet.com, whenavailable.com, and Doodle, then differentiate via completion-first flow and MCP-enabled agent orchestration
+  - Meeting input: visual direction should feel friendly and colorful with blues/greens, while remaining minimalistic and clean
 - 👤 Una the User (workflow pain, trust, usability expectations)
   - Meeting input: group chat coordination is fragmented, and most availability responses happen on phones
+  - Meeting input: competitor tools are familiar but can feel clunky in mobile usage and ambiguous around final plan confidence
 
 ## Clarity resolved before implementation
 
@@ -29,6 +32,12 @@ This document now captures clarified answers and decisions before implementation
   - Enterprise admin controls, deep integrations, and complex recurring scheduling
 - What is the MVP access model for participation and hosting?
   - No required accounts in MVP; anyone can create a schedule and receive a private host link to manage details and view results
+- What are the explicit MVP routes and responsibilities?
+  - Home route (`/`): host selects start/end dates with standard date inputs and initial available schedule slots, then clicks "Create schedule"
+  - Host dashboard route (`/s/{scheduleKey}/{hostKey}`): host can copy/share both links (public schedule link and private host dashboard link), edit schedule details/date/slot availability, and review attendee responses
+  - Attendee schedule route (`/s/{scheduleKey}`): attendees enter name and select available slots; this route must be especially mobile friendly
+- Why build instead of just adopting existing tools?
+  - Existing tools like when2meet.com, whenavailable.com, and Doodle validate demand, but we still need a tighter completion-first UX and agent-native workflows (AI agents using MCP to create, update, and finalize plans with users)
 
 ### Success clarity
 
@@ -39,6 +48,11 @@ This document now captures clarified answers and decisions before implementation
   - Median time from poll creation to finalized time
 - What failure signal indicates the MVP is not working?
   - Many polls created, but few result in a confirmed plan
+- What UX quality bar should support the success metric?
+  - Availability selection should feel spreadsheet-fast: like selecting time-slot cells in Excel on desktop, with clear visual state and low interaction friction
+  - Proposed implementation direction from product/developer facilitation: on mobile, tap-to-select plus draggable corner handle expansion with edge auto-scroll
+  - Overall product aesthetics should feel friendly and colorful (primarily blues/greens) without losing a minimalistic, clean interface
+  - Route transitions should be direct and explicit: create on `/`, manage on `/s/{scheduleKey}/{hostKey}`, collect attendee availability on `/s/{scheduleKey}`
 
 ### Constraint clarity
 
@@ -50,13 +64,17 @@ This document now captures clarified answers and decisions before implementation
   - Keep participant data minimal and avoid exposing private contact details
 - Technical constraints that could force tradeoffs
   - Use the existing web stack with lightweight sharing links and a mobile-first web experience
+  - Preserve an interaction model that supports drag selection and future MCP-triggered scheduling actions without complex rewrites
+  - Route model should keep host and attendee capabilities clearly separated while preserving easy sharing
 
 ### Risk clarity
 
 - Top risks most likely to cause MVP failure
   - Poor mobile UX leading to incomplete availability submissions
   - Low invitee response rate
   - Scope creep from adding too many features in v1
+  - UX interaction complexity for touch devices (selection, drag handles, and edge auto-scroll) causing accidental input
+  - Confusion between host and attendee links causing incorrect sharing or lost host control
 - What evidence would indicate each risk is becoming real?
   - Polls with low completion
   - Low response rates despite poll creation
@@ -66,6 +84,8 @@ This document now captures clarified answers and decisions before implementation
   - Frictionless response flow with clearer status tracking
   - Avoid mandatory account creation in MVP; use private host link access for management
   - Limit v1 to a narrow set of social planning flows
+  - Adopt proven interaction patterns: desktop cell selection inspired by spreadsheet tools, and mobile selection behavior similar to Google Sheets (tap cell, drag corner dot to expand, edge-drag auto-scroll)
+  - Make route purpose explicit in UI copy and provide clear copy/share controls for both schedule and host links
 
 ## Questions asked in the meeting
 
@@ -81,6 +101,16 @@ This document now captures clarified answers and decisions before implementation
   - Not in v1. Defer accounts and prioritize participation completion
 - How should hosts manage events in MVP without accounts?
   - Issue a private host dashboard link on event creation
+- What should the core route map be for MVP?
+  - `/` for schedule creation, `/s/{scheduleKey}/{hostKey}` for host management, `/s/{scheduleKey}` for attendee responses
+- What capabilities must the host dashboard include on first release?
+  - Easy copy/share for both links, schedule/date/slot editing controls, and attendee response visibility
+- If existing scheduling tools already work, why build this?
+  - We need a differentiated UX for reliable plan completion plus AI-agent orchestration via MCP, not just another availability poll
+- Where are we drawing UX inspiration and which competitors should guide baseline expectations?
+  - when2meet.com, whenavailable.com, and Doodle
+- What should the design feel like and look like?
+  - Friendly and colorful with a calm blue/green palette, but still minimalistic and clean so core scheduling actions stay visually obvious
 
 ### For 👤 Una the User
 
@@ -94,6 +124,16 @@ This document now captures clarified answers and decisions before implementation
   - No. The use case is too infrequent for most users to install an app; mobile web is sufficient
 - Should participants be required to create accounts?
   - No. Account creation adds too much friction for an infrequent-use flow
+- What should attendees do on the schedule page?
+  - Enter a name and select available slots on `/s/{scheduleKey}`
+- Which existing tools and interaction patterns feel familiar enough to borrow?
+  - when2meet.com, whenavailable.com, and Doodle are familiar references
+- How do those competitor experiences feel in real use?
+  - Familiar enough to start quickly, but clunky on phones and still weak on clear finalization confidence
+- What should mobile time-slot selection feel like?
+  - Kody's proposed direction validated by user feedback: similar to Google Sheets mobile selection (tap a start cell, drag a corner handle to expand selected slots, auto-scroll near view edges)
+- Which route is most sensitive to mobile usability quality?
+  - `/s/{scheduleKey}` attendee submission flow, because most invitees respond on phones
 
 ## Assumptions to test
 
@@ -114,3 +154,15 @@ This document now captures clarified answers and decisions before implementation
     - A narrow set of social planning use cases is enough to validate viability
   - How we will validate it:
     - Measure completion and repeat usage across the initial social planning cohorts
+
+- Assumption:
+  - Why we believe this:
+    - Familiar spreadsheet-like slot selection (desktop) and Google Sheets-like touch selection (mobile) will reduce cognitive load and improve completion rates
+  - How we will validate it:
+    - Track response-completion and error-correction rates across desktop and mobile cohorts, and compare against baseline interaction prototypes
+
+- Assumption:
+  - Why we believe this:
+    - Explicit route separation (`/`, `/s/{scheduleKey}/{hostKey}`, `/s/{scheduleKey}`) will reduce user confusion while preserving fast sharing
+  - How we will validate it:
+    - Track host-link misuse rates, attendee completion rates, and support friction signals related to link-sharing mistakes

exercises/01.building-an-mvp/02.solution.stakeholder-meeting/meeting-transcript.md

@@ -35,13 +35,46 @@ existing tools do not solve well, and we can define success against that gap.
 💼 Brett: Exactly. If we cannot outperform the default chat-plus-poll behavior on
 finalized plans, we should stop and not keep investing.
 
+🐨 Kody: Where are we going to draw inspiration for the user experience? Which
+competitors should we study directly?
+
+💼 Brett: Start with when2meet.com, whenavailable.com, and Doodle. Those are the
+closest references for how people already think about sharing availability.
+
+🐨 Kody: Great. Una, what do those experiences feel like in real use?
+
+👤 Una: They are familiar enough to get people started quickly, which is good.
+But they also feel clunky when chats are messy and the final plan is still
+unclear.
+
+👤 Una: On phones, the biggest issue is interaction friction. If selecting slots
+is awkward, people stop midway and go back to chat.
+
+💼 Brett: That is why we should build our own instead of just adopting one tool.
+We can keep familiar interaction patterns, but improve completion and integrate
+cleanly with AI agents via MCP.
+
+🐨 Kody: What should the design feel like and look like?
+
+💼 Brett: I want it to feel like planning with friends, not filling out a stiff
+form. Friendly energy, clear momentum, and no visual intimidation.
+
+💼 Brett: Color-wise, I keep picturing blues and greens because they feel calm,
+optimistic, and trustworthy for coordination.
+
+💼 Brett: At the same time, I do not want visual noise. It should stay minimal and
+clean so the schedule grid and final decision stand out.
+
+🐨 Kody: Good direction. We can tune the existing design system/theme foundation to
+that style instead of inventing a brand-new visual system.
+
 🐨 Kody: Una, from your perspective, what is the most painful part of coordinating a
 plan today?
 
 👤 Una: My pain is that group chats get noisy, people miss messages, and nobody knows
 if a plan is actually confirmed.
 
-🐨 Kody: For objective, should we optimize for poll creation or finalized plans?
+🐨 Kody: What should the MVP optimize for first?
 
 💼 Brett: Honestly, my instinct is we should make it feel complete from day one.
 I am thinking polished invites, reminders, some level of calendar connection,
@@ -135,9 +168,25 @@ people will go back to chat.
 👤 Una: Also, most people in my groups will respond on their phones, not desktop.
 If the mobile experience is clunky, they simply will not finish availability.
 
+🐨 Kody: Mobile usage is core for this audience. I want to design that interaction
+intentionally.
+
+👤 Una: Agreed. If mobile feels awkward, people will not finish.
+
 🐨 Kody: Great call. So mobile-first UX is not optional; it is part of core
 viability.
 
+🐨 Kody: One direction I would propose is a spreadsheet-like model: select time
+slots like Excel cells on desktop, then on mobile tap a cell and drag a corner
+handle like Google Sheets to expand the range.
+
+🐨 Kody: If the drag reaches near the edge, we should auto-scroll so people can
+continue selecting without lifting their finger. Does that match what would feel
+natural?
+
+👤 Una: Yes, that would feel natural. The key is that it stays obvious and easy to
+control.
+
 🐨 Kody: Is a native mobile app on the table for this MVP?
 
 👤 Una: Honestly, no. This is too infrequent for most people to install an app.
@@ -156,6 +205,30 @@ to manage event details and view results.
 
 👤 Una: That works. As long as the host link is clear and easy to find again.
 
+🐨 Kody: Let’s make routes explicit so implementation and UX stay aligned. On the
+home page (`/`), the host should pick start/end dates using standard date
+inputs, select the time slots they want in the schedule, then tap a "Create
+schedule" button. Does that match the expected first step?
+
+💼 Brett: Yes, that is exactly the creation flow we need.
+
+🐨 Kody: After create, we should route to the host dashboard at
+`/s/{scheduleKey}/{hostKey}`.
+
+💼 Brett: Correct. That page must make it easy to copy/share both links: the
+public attendee schedule link and the private host dashboard link.
+
+🐨 Kody: And on that same host dashboard, hosts need clear controls to edit the
+date range and available slot times, plus a live view of attendee responses.
+
+💼 Brett: Yes. If host edits are awkward, coordination falls apart.
+
+🐨 Kody: The attendee route should be `/s/{scheduleKey}`, which is the link hosts
+send out.
+
+👤 Una: Perfect. On that page, attendees should enter their name and mark the
+time slots they can do. That flow has to be very mobile friendly.
+
 🐨 Kody: What constraints should shape scope immediately?
 
 💼 Brett: I want this to feel premium right away. I know that is not a hard

exercises/01.building-an-mvp/03.solution.select-starter-architecture/README.mdx

@@ -11,3 +11,4 @@ Use these references:
 - <InlineFile file="starter-requirements.md" />
 - <InlineFile file="starter-decision.md" />
 - <InlineFile file="kellie-technical-transcript.md" />
+- <InlineFile file="implementation-brief.md" />