4.6 KiB
Guided Activation Flow Feature Spec
Overview
This feature introduces a post-setup guided activation flow for new companies.
After completing the setup wizard, users should be guided through their first real workflow so they understand how to use the system immediately.
This is NOT a tooltip tour.
This is a guided outcome flow using real system actions (quotes, jobs, invoices).
Problem
Current behavior:
- Users complete setup wizard
- Land on dashboard
- Do not create quotes, jobs, or invoices
- Drop off
Goal:
- Ensure users complete at least ONE real workflow
- Create an "aha moment" within first session
Business Workflows
1. Quote-First Workflow
- Create Quote
- Send to customer
- Convert Quote → Job
- Process Job
- Create Invoice
- Customer Pays
2. Job-First Workflow (Walk-in)
- Create Job directly
- Process Job
- Create Invoice
- Customer Pays
Feature Behavior
Trigger Condition
IF:
- setup wizard is completed
- AND firstWorkflowCompleted == false
THEN: → redirect user to guided activation flow
Step 1: Workflow Selection
Display full-screen page:
Title:
"Your shop is set up. Let’s run your first workflow."
Subtitle:
"Choose how jobs usually start for your shop and we’ll guide you through it."
Question:
"How do jobs usually start for your shop?"
Options:
Option A:
Title: "I send a quote first" Description: "Create a quote, convert it to a job, then invoice when work is complete."
Option B:
Title: "I start with a job" Description: "For walk-ins or approved work where you start immediately."
On Selection:
Save:
- onboardingPath = "quote_first" | "job_first"
Then continue into guided flow
Step 2: Guided Flow
Path A — Quote First
Step A1: Create Quote
- Use existing quote creation logic
- Pre-fill fields:
- Customer: "Sample Customer"
- Item: "Wheel Set"
- Quantity: 4
- Notes: "Sample onboarding quote"
- Allow editing before submit
Step A2: Show Quote Created
Message: "This is the quote you would send to your customer."
CTA: "Convert to Job"
Step A3: Convert Quote → Job
- Use existing conversion logic
Step A4: Show Job
Message: "This job is now tracked in your workflow."
CTA: "Create Invoice" (if supported)
Step A5: Create Invoice (optional)
- Use existing invoice logic
Completion:
Set:
- firstWorkflowCompleted = true
Path B — Job First
Step B1: Create Job
- Use existing job creation logic
- Pre-fill:
- Customer: "Walk-in Customer"
- Item: "Wheel Set"
- Quantity: 4
- Notes: "Sample onboarding job"
Step B2: Show Job
Message: "This job is now in your workflow."
CTA: "Create Invoice" (optional)
Step B3: Create Invoice (optional)
Completion:
Set:
- firstWorkflowCompleted = true
Skipping
Provide "Skip for now" option.
If skipped:
- DO NOT set firstWorkflowCompleted
- Redirect to dashboard
- Continue showing activation banner
Dashboard Behavior
If:
- setup complete
- AND firstWorkflowCompleted == false
Show persistent banner:
Title: "Create your first job or quote"
Text: "Run a quick 2-minute workflow to see how the system works."
CTA: "Start first workflow"
Data Model Changes
Add to Company or User:
- onboardingPath: string | null
- firstWorkflowCompleted: boolean
Optional:
- firstQuoteCreatedAt: datetime
- firstJobCreatedAt: datetime
- firstInvoiceCreatedAt: datetime
Events / Tracking (if system exists)
Track:
- onboarding_path_selected
- first_quote_created
- first_job_created
- first_invoice_created
- first_workflow_completed
- first_workflow_skipped
Implementation Constraints
- MUST reuse existing quote/job/invoice logic
- DO NOT duplicate business logic
- DO NOT create separate fake systems
- Use existing forms and APIs where possible
- Keep UI minimal and fast
- Pre-fill as much as possible
UX Requirements
- No tooltip tours
- Linear guided flow only
- One action at a time
- Minimize user effort
- Show immediate visual feedback
Developer Instructions
Before coding:
- Inspect setup wizard completion logic
- Identify routing after setup
- Identify quote/job/invoice creation flows
- Identify data model structure
Then: 5. Propose implementation plan 6. Wait for approval 7. Implement incrementally 8. Summarize changes 9. Provide manual QA steps
Success Criteria
- % of users creating first job increases significantly
- Users complete at least one workflow during onboarding
- Reduced drop-off after setup wizard
Target: ≥ 30% of new users create at least one job or quote