1. Product Vision - The "why" and business value
2. User Personas & Journeys - Who uses it and their goals
3. Core Workflows - Step-by-step user actions
4. Data & Entities - What information the system manages
5. Edge Cases & Boundaries - What could go wrong
6. Success Criteria - How we measure success
7. Constraints & Integration - Technical limitations and existing systems

• "Walk me through exactly what happens when..."
• "What if the user tries to..."
• "How do you handle the case where..."
• "What data do you need to capture at this point?"
• "Who else is involved in this workflow?"

• "In similar SaaS products, teams typically..."
• "Industry standard for this workflow is..."
• "Let me suggest three common approaches: A, B, C..."
• "The trade-offs to consider here are..."
• "Most successful products handle this by..."

1. Elevator Pitch
   • "Describe your SaaS in one sentence. Who is it for, what problem does it solve?"
   • If unclear: "Let me help. Is this for [persona type]? Does it help them [achieve goal]?"
2. Core Value Proposition
   • "What is the #1 thing users will love about this product?"
   • "Why would someone choose this over [alternative/competitor]?"
3. Business Model
   • "How does this make money? (Subscription, usage-based, freemium, etc.)"
   • If unsure: "Common SaaS models: monthly subscription ($X/user), tiered plans, usage-based. Which fits best?"
4. Success Definition
   • "In 6 months, how do you know this is successful? (Users, revenue, engagement?)"
   • If vague: "Let's set concrete targets: X active users, $Y MRR, or Z key actions per user?"

undefined

1. Primary Personas
   • "Who are the main users? (Roles, not just 'users')"
   • Examples: "Admin, Member, Viewer? Or Manager, Team Lead, Individual Contributor?"
2. Persona Goals
   • For each persona: "What are they trying to achieve when they use your product?"
   • "What does success look like for [persona]?"
3. Persona Pain Points
   • "What frustrates [persona] today with existing solutions?"
   • If blank: "Common pains in this space: too complex, too slow, missing key feature X. Which apply?"
4. User Journey Overview
   • "Walk me through [persona]'s first use of the product. What do they do?"
   • "What about their daily/weekly usage pattern?"

undefined

• Goal: [What they want to achieve]
• Pain Points: [Current frustrations]
• Journey: [How they use the product]

• Goal: [What they want to achieve]
• Pain Points: [Current frustrations]
• Journey: [How they use the product]

---

1. Identify Workflows
   • "What are the top 3-5 things users do in the product?"
   • Examples: "Create project, invite team, track progress, generate reports?"
2. Workflow Deep-Dive (For EACH workflow):
   Step-by-step extraction:
   • "Let's start with [workflow]. The user clicks/opens [where]?"
   • "What's the very first thing they see?"
   • "What do they fill in or click next?"
   • "Are any fields required? Optional? Have defaults?"
   • "What happens when they click [Submit/Save/Next]?"
   • "What do they see after that action completes?"
   • "Can they go back and edit? How?"
   Decision points:
   • "Are there different paths based on [user type/data/condition]?"
   • "What if they choose Option A vs Option B?"
   Error cases:
   • "What if they leave required fields empty?"
   • "What if they enter invalid data?"
   • "What if the operation fails (network error, server error)?"
   Permissions:
   • "Can everyone do this, or only certain roles?"
   • "What happens if an unauthorized user tries this action?"

undefined

1. User sees modal/form with fields:
   • Project Name (required, text, max 100 chars)
   • Description (optional, textarea, max 500 chars)
   • Team Members (optional, multi-select from organization users)
   • Due Date (optional, date picker)
   • Status (dropdown: "Planning", "Active", "On Hold")
2. User fills in fields
3. User clicks "Create Project"
4. System validates:
   • Name not empty
   • Name unique within organization
   • Due date not in past (if provided)
5. On success:
   • Project created in database
   • User redirected to project detail page
   • Success message: "Project [name] created successfully"
6. On validation failure:
   • Errors displayed inline below fields
   • Form data preserved
   • Focus moved to first error field

• Empty name → "Project name is required"
• Duplicate name → "Project with this name already exists"
• Invalid date → "Due date cannot be in the past"
• Network error → "Unable to create project. Please try again."

• Admin, Manager: Can create projects
• Member, Viewer: Cannot create projects (button hidden)

• User creates project with same name as deleted project → Allowed
• User creates 100+ projects → No limit (add pagination to project list)

**I repeat this for EVERY workflow.**

---

1. Core Entities
   • "What are the main 'things' your system manages?"
   • Examples: "Projects, Tasks, Users, Teams, Files, Comments?"
2. Entity Attributes (For EACH entity):
   • "What information do you need to track about [entity]?"
   • "What's required vs optional?"
   • "Any unique constraints? (e.g., email must be unique)"
   • "Any default values?"
3. Relationships
   • "How do these entities relate to each other?"
   • "Is it one-to-many? Many-to-many?"
   • Example: "Can a Project have multiple Tasks? Can a Task belong to multiple Projects?"
4. Multi-Tenancy
   • "Is data isolated per organization/company/account?"
   • "Can users belong to multiple organizations?"
   • Guide: "Standard SaaS: Organization is the tenant. All data scoped to Organization."

undefined

• id

  (UUID, auto-generated)

• name

  (string, required, max 100, unique per org)

• description

  (text, optional, max 500)

• status

  (enum: "Planning", "Active", "On Hold", "Completed", default: "Planning")

• due_date

  (date, optional)

• organization_id

  (UUID, FK → Organization, required)

• created_by

  (UUID, FK → User, required)

• created_at

  (timestamp, auto)

• updated_at

  (timestamp, auto)

• Belongs to Organization (many-to-one)
• Created by User (many-to-one)
• Has many Tasks (one-to-many)

• id

  (UUID, auto-generated)

• title

  (string, required, max 200)

• description

  (text, optional)

• status

  (enum: "Todo", "In Progress", "Done", default: "Todo")

• priority

  (enum: "Low", "Medium", "High", default: "Medium")

• project_id

  (UUID, FK → Project, required)

• assigned_to

  (UUID, FK → User, optional)

• due_date

  (date, optional)

• organization_id

  (UUID, FK → Organization, required)

• created_at

  (timestamp, auto)

• updated_at

  (timestamp, auto)

• Belongs to Project (many-to-one)
• Belongs to Organization (many-to-one)
• Assigned to User (many-to-one, optional)

---

1. Boundary Conditions
   • "What's the maximum [users/projects/tasks/files] a user can have?"
   • "What's the minimum? (Can they have zero?)"
   • "What happens at scale? (1000+ items in a list)"
2. Concurrent Operations
   • "What if two users edit the same [entity] at the same time?"
   • Guide: "Common approaches: last-write-wins, optimistic locking, or conflict detection?"
3. Deletion & Cascades
   • "What happens when a [parent entity] is deleted?"
   • Example: "Delete project → Delete all tasks? Or prevent deletion if tasks exist?"
4. Invalid States
   • "Can a [entity] be in an invalid state?"
   • Example: "Can a task be assigned to a user not in the project's organization?"
5. External Dependencies
   • "Does this integrate with external services? (Payment, email, storage?)"
   • "What happens if those services are down?"

undefined

• Max projects per organization: 1000
• Max tasks per project: 5000
• Max file upload size: 10MB

• Approach: Optimistic locking (last-write-wins with timestamp check)
• UI shows "This item was updated by [user]. Refresh to see latest."

• Delete Project → Soft delete (mark as deleted, keep tasks)
• Delete User → Reassign tasks to project owner, maintain audit trail

• Task cannot be assigned to user outside organization
• Project due date cannot be before earliest task due date

• Email (SendGrid): Queue emails, retry on failure, show warning if delivery fails
• File Storage (S3): Direct upload, show error if upload fails

---

1. Acceptance Criteria (For each workflow):
   • "How do you know [workflow] is working correctly?"
   • "What's the expected outcome?"
   • "What should NOT happen?"
2. User Experience
   • "What makes a good experience for this workflow?"
   • "What would frustrate users?"
   • Guide: "Best practices: fast (<2s), clear feedback, recoverable errors"
3. Performance
   • "How fast should this be?"
   • "How many concurrent users will you have?"
   • Guide: "Standard SaaS: <2s page load, <500ms API response, 100-1000 concurrent users"
4. Quality Standards
   • "What level of testing do you want?"
   • Guide: "We recommend 90% test coverage: API (40%), UI (45%), E2E (15%)"

undefined

• ✅ Project created in database with unique ID
• ✅ User redirected to project detail page
• ✅ Project appears in user's project list
• ✅ Success message displayed

• Form loads in <1s
• Validation errors shown immediately (client-side)
• Submit completes in <2s
• Clear feedback on success/failure

• ❌ Duplicate names rejected with clear error
• ❌ Invalid data prevented with inline validation
• ❌ Network errors show retry option

• API response time: <500ms (95th percentile)
• Page load time: <2s (95th percentile)
• Concurrent users: 500
• Database queries: <100ms

• Test coverage: 90% (API: 40%, UI: 45%, E2E: 15%)
• All workflows have Gherkin scenarios
• All acceptance criteria mapped to tests

---

1. Technical Constraints
   • "Are there any technology requirements? (Specific frameworks, languages, cloud providers?)"
   • "Any compliance requirements? (GDPR, HIPAA, SOC2?)"
   • "Any performance requirements we haven't covered?"
2. Existing Systems
   • "Does this need to integrate with existing systems?"
   • "Do you have existing user data to import?"
   • "Do you have existing authentication? (SSO, SAML, OAuth?)"
3. Budget & Timeline
   • "What's your target launch date?"
   • "Any hard deadlines?"
   • Guide: "Typical MVP: 8-12 weeks for 5-7 core workflows"
4. Team & Resources
   • "Who's building this? (Solo, small team, agency?)"
   • "What's your deployment preference? (Cloud, on-premise, both?)"
   • Guide: "We recommend: Next.js + NestJS (Apso) + PostgreSQL + Vercel"

undefined

• Tech Stack: Next.js 14 (App Router), NestJS (via Apso), PostgreSQL, Better Auth
• Cloud Provider: Vercel (frontend), Railway (backend + database)
• Compliance: GDPR (EU users)

• Authentication: Better Auth (email/password + Google OAuth)
• Email: SendGrid (transactional emails)
• File Storage: AWS S3 (user uploads)
• Payments: Stripe (subscription billing)

• Target Launch: 12 weeks from kickoff
• MVP Scope: 5 core workflows
• Hard Deadline: None

• Solo developer
• Using Claude Code for implementation
• Deploying to Vercel + Railway

• Staging environment: Required
• Production environment: Vercel + Railway
• CI/CD: GitHub Actions

---

1. Completeness Check
   • "Have we covered all the workflows you mentioned?"
   • "Any features we missed?"
   • "Any user types we didn't discuss?"
2. Prioritization
   • "If you had to launch with only 3 workflows, which would they be?"
   • "What can wait for v2?"
3. Confidence Check
   • "On a scale of 1-10, how confident are you in what we've defined?"
   • If <8: "What areas feel unclear? Let's dig deeper."
4. Next Steps Alignment
   • "I'll now create a complete discovery document. Does this format work for you?"
   • "After discovery, we'll write Gherkin scenarios. Ready to proceed?"

undefined

1. User authentication (login, signup, logout)
2. Create/view/edit projects
3. Create/view/edit tasks

1. Task assignment
2. Project collaboration (comments)

1. File attachments
2. Notifications
3. Reporting/analytics

1. ✅ Discovery complete
2. ⏭️ Generate Gherkin scenarios from workflows
3. ⏭️ Extract schema from data model
4. ⏭️ Write product brief referencing scenarios
5. ⏭️ Create phased roadmap
6. ⏭️ Begin implementation

"Let me guide you with industry standards. Most project management SaaS products track:

Essential:

• Name/title (what is it?)
• Description (what's it about?)
• Status (what state is it in?)
• Owner/creator (who's responsible?)

Common additions:

• Due date (when should it finish?)
• Priority (how important?)
• Tags/labels (how to categorize?)

For your use case, which of these do you need? Any others specific to your domain?"

"Great question! Let me break down the trade-offs:

Option A: One project per task (many-to-one)

• ✅ Simpler data model
• ✅ Clearer ownership
• ❌ Can't share tasks across projects
• Best for: Clear project boundaries, independent projects

Option B: Multiple projects per task (many-to-many)

• ✅ Flexible task sharing
• ✅ Supports cross-project collaboration
• ❌ More complex queries
• ❌ Harder to understand task ownership
• Best for: Matrix organizations, shared resources

Industry standard: 80% of project management tools use Option A. Tasks belong to one project. If you need cross-project visibility, use 'linked tasks' or 'dependencies' instead.

Which model fits your users' mental model?"

"Let me validate against SaaS best practices:

✅ Good:

• Clear user action triggers
• Validation at right points
• Error handling defined

⚠️ Consider:

• Add confirmation for destructive actions (delete)
• Add loading states for async operations
• Add undo for accidental changes

🎯 Recommendation: Add a confirmation modal when deleting projects: 'Are you sure? This will also delete X tasks.' Include 'Keep' and 'Delete' buttons."

• Starting a new SaaS project (always start here!)
• Defining a major new feature area
• Validating or refining requirements
• You have an idea but unclear requirements
• Re-discovering a stalled project

• First-time SaaS builders (I guide you through unknowns)
• Complex domains (I help extract hidden requirements)
• Multi-persona products (I ensure all users covered)
• Regulated industries (I ensure compliance considerations)

• Small feature additions to existing product (use feature-builder)
• Bug fixes or refactoring (use appropriate skill)
• Updates to well-defined features

• Uses workflows to create Gherkin scenarios
• Uses acceptance criteria for assertions
• Uses edge cases for negative tests

• Uses data model section directly
• Extracts entities and relationships
• Applies multi-tenancy patterns

• Uses vision and personas
• References discovery document
• Links to workflows

• Uses prioritization section
• Phases workflows into releases
• Maps dependencies

• Discovery is Phase 0 (before all else)
• Orchestrator waits for discovery approval
• All subsequent phases reference discovery doc

• All core workflows documented step-by-step
• All entities defined with attributes
• All personas identified with goals
• All edge cases captured
• All integrations listed

• Workflows have clear trigger → steps → outcome
• Data model has types, constraints, relationships
• Acceptance criteria are measurable
• No ambiguous language ("maybe", "probably")

• Technical constraints identified
• Timeline realistic for scope
• Integration dependencies clear
• Performance targets achievable

• Each workflow links to personas
• Each entity links to workflows
• Each acceptance criterion links to workflow step
• Prioritization rationale documented

• references/discovery-framework.md

  - Structured interview techniques

• references/product-management-playbook.md

  - Best practices and industry standards