216 lines
13 KiB
Markdown
216 lines
13 KiB
Markdown
# Vision Schema
|
||
|
||
The `vision.json` file captures all founder answers from the PLAID intake conversation. It is the single input for document generation.
|
||
|
||
## Type Definition
|
||
|
||
```typescript
|
||
interface Vision {
|
||
meta: {
|
||
createdAt: string; // ISO 8601 timestamp
|
||
updatedAt: string; // ISO 8601 timestamp
|
||
version: "1.0"; // Schema version
|
||
plaidVersion: "1.0"; // PLAID skill version
|
||
};
|
||
|
||
creator: {
|
||
name: string; // Founder's name
|
||
expertise: string; // Professional background / area of expertise
|
||
background: string; // Their story — what led them here
|
||
};
|
||
|
||
purpose: {
|
||
whoYouHelp: string; // Target audience description
|
||
problemYouSolve: string; // The pain point
|
||
desiredTransformation: string; // Before → after for the user
|
||
whyYou: string; // Founder-market fit narrative
|
||
};
|
||
|
||
product: {
|
||
name: string; // Product name
|
||
oneLiner: string; // One-sentence description
|
||
howItWorks: string; // Core user flow narrative
|
||
keyCapabilities: string[]; // 3-5 main capabilities
|
||
platform: "web" | "mobile" | "desktop" | "cross-platform";
|
||
marketDifferentiation: string; // What makes it different
|
||
magicMoment: string; // The "aha" moment description
|
||
};
|
||
|
||
audience: {
|
||
primaryUser: string; // Detailed primary persona
|
||
secondaryUsers: string[]; // 2-3 secondary user groups
|
||
currentAlternatives: string; // What people use today
|
||
frustrations: string; // What's broken about alternatives
|
||
};
|
||
|
||
business: {
|
||
revenueModel: "subscription" | "freemium" | "one-time" | "marketplace" | "ad-supported" | "free";
|
||
initialGoal: string; // 90-day success definition
|
||
sixMonthVision: string; // 6-month vision
|
||
constraints: string; // Time, money, skills, etc.
|
||
goToMarket: string; // GTM approach
|
||
};
|
||
|
||
feeling: {
|
||
brandPersonality: string; // Brand personality archetype
|
||
visualMood: string; // Visual direction
|
||
toneOfVoice: string; // How the product communicates
|
||
antiPatterns: string; // What the product should never be
|
||
};
|
||
|
||
techStack: {
|
||
appType: "web" | "mobile" | "desktop" | "cross-platform";
|
||
frontend: {
|
||
choice: string; // e.g. "Next.js"
|
||
rationale: string; // Why this was chosen
|
||
};
|
||
backend: {
|
||
choice: string; // e.g. "Convex"
|
||
rationale: string;
|
||
};
|
||
database: {
|
||
choice: string; // e.g. "Convex Database"
|
||
rationale: string;
|
||
};
|
||
auth: {
|
||
choice: string; // e.g. "Clerk"
|
||
rationale: string;
|
||
};
|
||
payments: {
|
||
choice: string; // e.g. "Polar" — empty string if free
|
||
rationale: string;
|
||
};
|
||
};
|
||
|
||
tooling: {
|
||
codingAgent: "claude-code" | "cursor" | "windsurf" | "copilot" | "other";
|
||
codingAgentName?: string; // Only if codingAgent is "other"
|
||
};
|
||
}
|
||
```
|
||
|
||
## Schema Versioning
|
||
|
||
The `meta.version` field tracks the schema version — the shape of `vision.json` (what fields exist, their types, valid enum values). The `meta.plaidVersion` field tracks which version of the PLAID skill created the file.
|
||
|
||
When the schema changes (fields added, removed, renamed, or types changed), `CURRENT_VERSION` in `scripts/validate-vision.js` is bumped and a migration function is added to the `migrations` registry.
|
||
|
||
### How migrations work
|
||
|
||
- Each migration transforms a vision object from version N to version N+1.
|
||
- Migrations chain: a file at 1.0 migrates through 1.0→1.1→1.2 to reach the current version.
|
||
- Running `node scripts/validate-vision.js` without flags detects outdated files and reports what migrations are pending.
|
||
- Running `node scripts/validate-vision.js --migrate` applies all pending migrations in sequence, writes the updated file, and then validates it.
|
||
- Migrations update `meta.version` to the new version and set `meta.updatedAt` to the current timestamp.
|
||
|
||
### Adding a new migration
|
||
|
||
1. Bump `CURRENT_VERSION` in `scripts/validate-vision.js` (e.g. `'1.0'` → `'1.1'`).
|
||
2. Add an entry to the `migrations` object keyed by the version you're migrating FROM:
|
||
```javascript
|
||
'1.0': (vision) => {
|
||
// transform vision from 1.0 → 1.1
|
||
vision.meta.version = '1.1';
|
||
return vision;
|
||
}
|
||
```
|
||
3. Update the `validate()` function to check any new or changed fields.
|
||
4. Update this schema document and the example below to reflect the new shape.
|
||
|
||
## Field Rules
|
||
|
||
- **No empty strings** in required fields. If the founder skipped a question, use the AI-suggested default.
|
||
- **Arrays** (keyCapabilities, secondaryUsers) must have at least 1 item.
|
||
- **techStack.payments** can have empty strings for choice and rationale if revenue model is “free”.
|
||
- **techStack.database**, **techStack.auth**, and **techStack.payments** may have `"None"` as the choice value for mobile apps that don’t need these layers. Include a rationale explaining why (e.g. “App uses on-device storage only”).
|
||
- **tooling.codingAgentName** is only present when codingAgent is “other”.
|
||
- **meta.createdAt** and **meta.updatedAt** should be set to the current ISO 8601 timestamp when the file is first created.
|
||
|
||
## Example
|
||
|
||
```json
|
||
{
|
||
"meta": {
|
||
"createdAt": "2025-03-15T10:30:00Z",
|
||
"updatedAt": "2025-03-15T11:45:00Z",
|
||
"version": "1.0",
|
||
"plaidVersion": "1.0"
|
||
},
|
||
"creator": {
|
||
"name": "Sarah Chen",
|
||
"expertise": "UX design and user research — 8 years at enterprise SaaS companies",
|
||
"background": "I've spent nearly a decade watching enterprise software make simple tasks painful. I ran user research at two B2B SaaS companies and saw the same pattern: features shipped without talking to users, redesigns that made things worse, and research insights that lived in slide decks nobody read. I want to build the tool I wished I had."
|
||
},
|
||
"purpose": {
|
||
"whoYouHelp": "Product managers and UX researchers at mid-size SaaS companies (50-500 employees) who need to make user research a continuous practice, not a one-off project",
|
||
"problemYouSolve": "User research insights get trapped in documents, slide decks, and individual people's heads. When a PM needs to make a decision, they can't quickly find what the team already knows about their users. So they either guess, re-run research that was already done, or skip research entirely.",
|
||
"desiredTransformation": "Product teams make every decision with confidence because user insights are organized, searchable, and connected to the features they inform. Research becomes a living knowledge base, not a graveyard of PDFs.",
|
||
"whyYou": "I've been the researcher whose work got ignored because it was buried in Notion docs. I've also been the PM who couldn't find the research when I needed it. I've lived both sides of this problem and I know exactly where the handoff breaks down."
|
||
},
|
||
"product": {
|
||
"name": "InsightHub",
|
||
"oneLiner": "InsightHub helps product teams find and use their user research when making decisions.",
|
||
"howItWorks": "A researcher uploads interview notes, survey results, or usability test recordings. InsightHub automatically extracts key insights, tags them by theme and user segment, and links them to product areas. When a PM is working on a feature, they search InsightHub and instantly see every relevant insight the team has ever gathered — no more digging through docs.",
|
||
"keyCapabilities": [
|
||
"Automatic insight extraction from research documents and recordings",
|
||
"Semantic search across all research — find insights by concept, not just keywords",
|
||
"Insight-to-feature linking — connect research findings to product decisions",
|
||
"Research repository with tagging, filtering, and trend analysis",
|
||
"Team activity feed showing recent research and how it's being used"
|
||
],
|
||
"platform": "web",
|
||
"marketDifferentiation": "Unlike Dovetail and Condens which focus on analysis workflows, InsightHub focuses on the moment of decision — when a PM or designer needs an answer. It's not a research tool, it's a research memory that the whole team shares.",
|
||
"magicMoment": "A PM is debating a feature approach in a meeting. They search InsightHub, and within 10 seconds find three user interview quotes that directly address their question. The team makes a confident decision in minutes instead of scheduling another round of research."
|
||
},
|
||
"audience": {
|
||
"primaryUser": "Maya, 32, Senior PM at a 200-person B2B SaaS company. She manages a product area with 3 squads. Her researchers do great work but she can never find it when she needs it. She currently searches Notion, Slack, and Google Drive hoping to find relevant research before her sprint planning meeting.",
|
||
"secondaryUsers": [
|
||
"UX Researchers who want their work to have more impact and be discoverable by the broader team",
|
||
"Design leads who need research context when reviewing designs and making visual decisions",
|
||
"Engineering managers who want to understand the 'why' behind feature requests"
|
||
],
|
||
"currentAlternatives": "Dovetail (expensive, focused on analysis not retrieval), Notion databases (manual tagging, hard to search), Google Drive folders (chaotic, unsearchable), Confluence pages (where research goes to die), or just asking the researcher directly (doesn't scale, single point of failure)",
|
||
"frustrations": "Existing tools are either too heavyweight (Dovetail requires researchers to do extensive tagging and analysis before anything is useful) or too lightweight (Notion/Drive have no semantic understanding — you have to know the exact words to search for). The real frustration is the gap between 'we did the research' and 'we used the research.'"
|
||
},
|
||
"business": {
|
||
"revenueModel": "subscription",
|
||
"initialGoal": "5 paying teams within 90 days, $2,000 MRR, and a documented case study from one team showing how InsightHub changed their decision-making process",
|
||
"sixMonthVision": "50 paying teams, $15,000 MRR, recognized as a category-defining tool in the product management community. Featured in Lenny's Newsletter or a similar PM publication.",
|
||
"constraints": "Building part-time (20 hrs/week) while freelancing. Budget: $500/month for tools and infrastructure. Strong on design and UX, moderate on frontend development, limited backend experience — hence the need for a managed backend.",
|
||
"goToMarket": "Build in public on Twitter/X and LinkedIn, targeting the product management and UX research community. Share weekly insights about research operationalization. Launch beta on Product Hunt. Partner with 2-3 PM community leaders for early access reviews."
|
||
},
|
||
"feeling": {
|
||
"brandPersonality": "The sharp, organized friend who always knows where to find things. Calm confidence, not flashy. Think: a well-organized library run by someone who genuinely loves helping people find answers. Professional but warm.",
|
||
"visualMood": "Clean and structured with subtle warmth. Think Notion's clarity meets Linear's precision, but with softer edges and a warmer palette. Not sterile — the visual equivalent of a well-lit, organized workspace.",
|
||
"toneOfVoice": "Clear, helpful, and quietly confident. Speaks in plain language, never jargon. Celebrates the team's research without being cheesy. Example error: 'We couldn't find that insight — try broader search terms or check the filters.' Example success: 'Found 12 insights across 4 studies. The most relevant are highlighted.'",
|
||
"antiPatterns": "Never feel like enterprise software — no dense tables with tiny text, no overwhelming dashboards, no 'contact sales' gates. Never feel like a toy — no confetti animations, no gamification, no infantilizing copy. Never feel slow or heavy — if it takes more than 2 seconds to find an insight, something is wrong."
|
||
},
|
||
"techStack": {
|
||
"appType": "web",
|
||
"frontend": {
|
||
"choice": "Next.js",
|
||
"rationale": "Largest ecosystem, best AI coding tool support, excellent Convex integration, deploys easily to Vercel"
|
||
},
|
||
"backend": {
|
||
"choice": "Convex",
|
||
"rationale": "Real-time reactivity for team collaboration, zero backend boilerplate, built-in file storage for research documents, TypeScript end-to-end"
|
||
},
|
||
"database": {
|
||
"choice": "Convex Database",
|
||
"rationale": "Included with Convex backend, automatic indexing, ACID transactions, reactive queries for real-time updates"
|
||
},
|
||
"auth": {
|
||
"choice": "Clerk",
|
||
"rationale": "Pre-built UI components for fast implementation, organization/team management built in, generous free tier"
|
||
},
|
||
"payments": {
|
||
"choice": "Polar",
|
||
"rationale": "Built for SaaS subscriptions, developer-friendly API, handles billing portal, generous free tier"
|
||
}
|
||
},
|
||
"tooling": {
|
||
"codingAgent": "claude-code"
|
||
}
|
||
}
|
||
```
|