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

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

Bump CURRENT_VERSION in scripts/validate-vision.js (e.g. '1.0' → '1.1').

Add an entry to the migrations object keyed by the version you're migrating FROM:

'1.0': (vision) => {
  // transform vision from 1.0 → 1.1
  vision.meta.version = '1.1';
  return vision;
}

Update the validate() function to check any new or changed fields.
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

{
  "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"
  }
}

13 KiB Raw Permalink Blame History Unescape Escape