@su-record/vibe 2.9.18 → 2.9.20

package/skills/ui-ux-pro-max/rubrics/interaction-states.md

@@ -1,83 +1,83 @@
-# Required Interaction States Checklist
-
-Every interactive element must implement all applicable states. Missing states are P1–P2 findings.
-
----
-
-## State Definitions
-
-| State | Trigger | Visual Requirement | ARIA Requirement |
-|-------|---------|-------------------|-----------------|
-| **Default** | No user interaction | Base appearance defined with sufficient contrast | — |
-| **Hover** | Mouse enters element | Visible color, shadow, or opacity change | — |
-| **Focus** | Keyboard navigation / tab | Clearly visible focus ring (≥ 2px, non-color-only) | — |
-| **Active / Pressed** | Mouse down or tap | Distinct from hover (darker, scale-down, or depressed look) | `aria-pressed` on toggles |
-| **Disabled** | Element not actionable | Reduced opacity (≤ 50%) + `cursor: not-allowed` | `disabled` attr or `aria-disabled="true"` |
-| **Loading** | Async operation in progress | Spinner, skeleton, or progress bar replaces or overlays content | `aria-busy="true"` |
-| **Error** | Validation fails or operation fails | Error color on border/background + error message visible | `aria-invalid="true"` + `aria-describedby` pointing to error |
-| **Success** | Operation completes | Confirmation feedback (color change, checkmark, toast) | `aria-live` announcement |
-
----
-
-## Element-State Matrix
-
-Use this matrix to verify each element type has all required states implemented.
-
-| Element | Default | Hover | Focus | Active | Disabled | Loading | Error | Success |
-|---------|---------|-------|-------|--------|----------|---------|-------|---------|
-| Button (primary) | Required | Required | Required | Required | Required | Required | — | — |
-| Button (destructive) | Required | Required | Required | Required | Required | Required | — | — |
-| Link | Required | Required | Required | Required | — | — | — | — |
-| Text input | Required | Optional | Required | — | Required | — | Required | Optional |
-| Select / dropdown | Required | Required | Required | — | Required | — | Required | — |
-| Checkbox | Required | Required | Required | Required | Required | — | — | — |
-| Radio button | Required | Required | Required | Required | Required | — | — | — |
-| Toggle / switch | Required | Required | Required | Required | Required | — | — | — |
-| Form submit button | Required | Required | Required | Required | Required | Required | — | Required |
-| Card (interactive) | Required | Required | Required | — | — | Required | — | — |
-| Tab | Required | Required | Required | Required | Required | — | — | — |
-| Menu item | Required | Required | Required | Required | Required | — | — | — |
-| Icon button | Required | Required | Required | Required | Required | Required | — | — |
-
----
-
-## Implementation Checklist
-
-### Hover
-- [ ] Color change uses a dedicated hover token (not inline opacity hack)
-- [ ] Transition applied (`transition-colors duration-150` or equivalent)
-- [ ] Layout does not shift on hover (no margin/padding changes)
-
-### Focus
-- [ ] Focus ring visible at 2:1 contrast against adjacent color
-- [ ] `outline: none` never used without a custom focus-visible replacement
-- [ ] `:focus-visible` used instead of `:focus` to avoid visible ring on mouse click
-
-### Active / Pressed
-- [ ] Distinct visual from hover state
-- [ ] `scale(0.97–0.98)` or darker color on press — not just removing hover
-- [ ] Touch devices: active state triggers on `touchstart`
-
-### Disabled
-- [ ] `opacity: 0.4–0.5` on disabled elements
-- [ ] `pointer-events: none` prevents interaction
-- [ ] `cursor: not-allowed` set
-- [ ] `disabled` attribute or `aria-disabled="true"` set on element
-- [ ] Disabled state does not rely on color alone
-
-### Loading
-- [ ] Original button/element width preserved during loading (no layout jump)
-- [ ] Spinner or skeleton shown within 100ms of action trigger
-- [ ] Interaction re-enabled after completion or error
-- [ ] `aria-busy="true"` set on loading container
-
-### Error
-- [ ] Error message visible near the element (not just a global toast)
-- [ ] Error styling uses `--color-error` token
-- [ ] `aria-invalid="true"` set on invalid input
-- [ ] Error message linked via `aria-describedby`
-
-### Success
-- [ ] Confirmation feedback shown within 300ms of completion
-- [ ] Success message auto-dismisses or provides clear dismiss action
-- [ ] `aria-live="polite"` region announces success to screen readers
+# Required Interaction States Checklist
+
+Every interactive element must implement all applicable states. Missing states are P1–P2 findings.
+
+---
+
+## State Definitions
+
+| State | Trigger | Visual Requirement | ARIA Requirement |
+|-------|---------|-------------------|-----------------|
+| **Default** | No user interaction | Base appearance defined with sufficient contrast | — |
+| **Hover** | Mouse enters element | Visible color, shadow, or opacity change | — |
+| **Focus** | Keyboard navigation / tab | Clearly visible focus ring (≥ 2px, non-color-only) | — |
+| **Active / Pressed** | Mouse down or tap | Distinct from hover (darker, scale-down, or depressed look) | `aria-pressed` on toggles |
+| **Disabled** | Element not actionable | Reduced opacity (≤ 50%) + `cursor: not-allowed` | `disabled` attr or `aria-disabled="true"` |
+| **Loading** | Async operation in progress | Spinner, skeleton, or progress bar replaces or overlays content | `aria-busy="true"` |
+| **Error** | Validation fails or operation fails | Error color on border/background + error message visible | `aria-invalid="true"` + `aria-describedby` pointing to error |
+| **Success** | Operation completes | Confirmation feedback (color change, checkmark, toast) | `aria-live` announcement |
+
+---
+
+## Element-State Matrix
+
+Use this matrix to verify each element type has all required states implemented.
+
+| Element | Default | Hover | Focus | Active | Disabled | Loading | Error | Success |
+|---------|---------|-------|-------|--------|----------|---------|-------|---------|
+| Button (primary) | Required | Required | Required | Required | Required | Required | — | — |
+| Button (destructive) | Required | Required | Required | Required | Required | Required | — | — |
+| Link | Required | Required | Required | Required | — | — | — | — |
+| Text input | Required | Optional | Required | — | Required | — | Required | Optional |
+| Select / dropdown | Required | Required | Required | — | Required | — | Required | — |
+| Checkbox | Required | Required | Required | Required | Required | — | — | — |
+| Radio button | Required | Required | Required | Required | Required | — | — | — |
+| Toggle / switch | Required | Required | Required | Required | Required | — | — | — |
+| Form submit button | Required | Required | Required | Required | Required | Required | — | Required |
+| Card (interactive) | Required | Required | Required | — | — | Required | — | — |
+| Tab | Required | Required | Required | Required | Required | — | — | — |
+| Menu item | Required | Required | Required | Required | Required | — | — | — |
+| Icon button | Required | Required | Required | Required | Required | Required | — | — |
+
+---
+
+## Implementation Checklist
+
+### Hover
+- [ ] Color change uses a dedicated hover token (not inline opacity hack)
+- [ ] Transition applied (`transition-colors duration-150` or equivalent)
+- [ ] Layout does not shift on hover (no margin/padding changes)
+
+### Focus
+- [ ] Focus ring visible at 2:1 contrast against adjacent color
+- [ ] `outline: none` never used without a custom focus-visible replacement
+- [ ] `:focus-visible` used instead of `:focus` to avoid visible ring on mouse click
+
+### Active / Pressed
+- [ ] Distinct visual from hover state
+- [ ] `scale(0.97–0.98)` or darker color on press — not just removing hover
+- [ ] Touch devices: active state triggers on `touchstart`
+
+### Disabled
+- [ ] `opacity: 0.4–0.5` on disabled elements
+- [ ] `pointer-events: none` prevents interaction
+- [ ] `cursor: not-allowed` set
+- [ ] `disabled` attribute or `aria-disabled="true"` set on element
+- [ ] Disabled state does not rely on color alone
+
+### Loading
+- [ ] Original button/element width preserved during loading (no layout jump)
+- [ ] Spinner or skeleton shown within 100ms of action trigger
+- [ ] Interaction re-enabled after completion or error
+- [ ] `aria-busy="true"` set on loading container
+
+### Error
+- [ ] Error message visible near the element (not just a global toast)
+- [ ] Error styling uses `--color-error` token
+- [ ] `aria-invalid="true"` set on invalid input
+- [ ] Error message linked via `aria-describedby`
+
+### Success
+- [ ] Confirmation feedback shown within 300ms of completion
+- [ ] Success message auto-dismisses or provides clear dismiss action
+- [ ] `aria-live="polite"` region announces success to screen readers

package/skills/ui-ux-pro-max/rubrics/responsive-breakpoints.md

@@ -1,99 +1,99 @@
-# Standard Breakpoint Definitions
-
-Reference for responsive design implementation across all stacks.
-
----
-
-## Core Breakpoints
-
-| Name | Min Width | Target Devices | Priority |
-|------|-----------|---------------|----------|
-| `xs` | 375px | Small phones (iPhone SE, Galaxy A) | Test target |
-| `sm` | 640px | Large phones (landscape), small tablets | Layout change |
-| `md` | 768px | Tablets (portrait), large phones | Major breakpoint |
-| `lg` | 1024px | Tablets (landscape), small laptops | Major breakpoint |
-| `xl` | 1280px | Standard desktop | Primary design target |
-| `2xl` | 1536px | Large monitors | Wide-layout target |
-
----
-
-## Framework Mappings
-
-| Breakpoint | Tailwind class | CSS media query | Common use |
-|------------|---------------|-----------------|------------|
-| Mobile default | (no prefix) | base styles | Mobile-first base |
-| sm | `sm:` | `@media (min-width: 640px)` | Large phone adjustments |
-| md | `md:` | `@media (min-width: 768px)` | Tablet layout |
-| lg | `lg:` | `@media (min-width: 1024px)` | Desktop layout |
-| xl | `xl:` | `@media (min-width: 1280px)` | Wide desktop |
-| 2xl | `2xl:` | `@media (min-width: 1536px)` | Ultra-wide |
-
----
-
-## Layout Behavior by Breakpoint
-
-### Navigation
-| Breakpoint | Pattern |
-|------------|---------|
-| < md | Hamburger menu / bottom tab bar |
-| md–lg | Collapsed sidebar or top nav with fewer items |
-| ≥ lg | Full sidebar or top nav with all items visible |
-
-### Content Grid
-| Breakpoint | Columns |
-|------------|---------|
-| xs–sm | 1 column |
-| md | 2 columns |
-| lg | 3 columns |
-| xl+ | 4 columns (data-heavy) or 3 columns (content) |
-
-### Typography Scale Adjustments
-| Element | Mobile | Desktop |
-|---------|--------|---------|
-| Hero heading | `text-3xl` (30px) | `text-5xl` (48px) |
-| Section heading | `text-xl` (20px) | `text-3xl` (30px) |
-| Body | `text-base` (16px) | `text-base` (16px) — never reduce below 16px |
-| Caption | `text-sm` (14px) | `text-sm` (14px) |
-
----
-
-## Touch Target Rules
-
-| Device | Minimum touch target | Recommended |
-|--------|---------------------|-------------|
-| Mobile (< md) | 44×44px | 48×48px |
-| Tablet (md–lg) | 44×44px | 44×44px |
-| Desktop (≥ lg) | 32×32px (mouse) | 36×36px |
-
----
-
-## Testing Checklist
-
-| Breakpoint | Must Verify |
-|------------|-------------|
-| 375px | No horizontal scroll; text readable; nav accessible; forms usable |
-| 768px | Layout transitions correctly; no content overlap |
-| 1024px | Desktop features visible; sidebar or nav fully expanded |
-| 1440px | Max-width container centered; content not stretched too wide |
-
-### Max-width containers
-
-| Use case | Recommended max-width |
-|----------|-----------------------|
-| Marketing / landing pages | `max-w-5xl` (1024px) or `max-w-6xl` (1152px) |
-| Application layouts | `max-w-7xl` (1280px) |
-| Reading / article content | `max-w-2xl` (672px) or `max-w-3xl` (768px) |
-| Full-bleed dashboards | None (use grid with sidebars) |
-
----
-
-## Container Query Usage
-
-Use `@container` when a component's layout depends on its parent width, not the viewport.
-
-| Scenario | Use viewport breakpoint | Use container query |
-|----------|------------------------|---------------------|
-| Page-level layout | Yes | No |
-| Component in sidebar vs main | No | Yes |
-| Card grid columns | No | Yes |
-| Navbar collapsing | Yes | No |
+# Standard Breakpoint Definitions
+
+Reference for responsive design implementation across all stacks.
+
+---
+
+## Core Breakpoints
+
+| Name | Min Width | Target Devices | Priority |
+|------|-----------|---------------|----------|
+| `xs` | 375px | Small phones (iPhone SE, Galaxy A) | Test target |
+| `sm` | 640px | Large phones (landscape), small tablets | Layout change |
+| `md` | 768px | Tablets (portrait), large phones | Major breakpoint |
+| `lg` | 1024px | Tablets (landscape), small laptops | Major breakpoint |
+| `xl` | 1280px | Standard desktop | Primary design target |
+| `2xl` | 1536px | Large monitors | Wide-layout target |
+
+---
+
+## Framework Mappings
+
+| Breakpoint | Tailwind class | CSS media query | Common use |
+|------------|---------------|-----------------|------------|
+| Mobile default | (no prefix) | base styles | Mobile-first base |
+| sm | `sm:` | `@media (min-width: 640px)` | Large phone adjustments |
+| md | `md:` | `@media (min-width: 768px)` | Tablet layout |
+| lg | `lg:` | `@media (min-width: 1024px)` | Desktop layout |
+| xl | `xl:` | `@media (min-width: 1280px)` | Wide desktop |
+| 2xl | `2xl:` | `@media (min-width: 1536px)` | Ultra-wide |
+
+---
+
+## Layout Behavior by Breakpoint
+
+### Navigation
+| Breakpoint | Pattern |
+|------------|---------|
+| < md | Hamburger menu / bottom tab bar |
+| md–lg | Collapsed sidebar or top nav with fewer items |
+| ≥ lg | Full sidebar or top nav with all items visible |
+
+### Content Grid
+| Breakpoint | Columns |
+|------------|---------|
+| xs–sm | 1 column |
+| md | 2 columns |
+| lg | 3 columns |
+| xl+ | 4 columns (data-heavy) or 3 columns (content) |
+
+### Typography Scale Adjustments
+| Element | Mobile | Desktop |
+|---------|--------|---------|
+| Hero heading | `text-3xl` (30px) | `text-5xl` (48px) |
+| Section heading | `text-xl` (20px) | `text-3xl` (30px) |
+| Body | `text-base` (16px) | `text-base` (16px) — never reduce below 16px |
+| Caption | `text-sm` (14px) | `text-sm` (14px) |
+
+---
+
+## Touch Target Rules
+
+| Device | Minimum touch target | Recommended |
+|--------|---------------------|-------------|
+| Mobile (< md) | 44×44px | 48×48px |
+| Tablet (md–lg) | 44×44px | 44×44px |
+| Desktop (≥ lg) | 32×32px (mouse) | 36×36px |
+
+---
+
+## Testing Checklist
+
+| Breakpoint | Must Verify |
+|------------|-------------|
+| 375px | No horizontal scroll; text readable; nav accessible; forms usable |
+| 768px | Layout transitions correctly; no content overlap |
+| 1024px | Desktop features visible; sidebar or nav fully expanded |
+| 1440px | Max-width container centered; content not stretched too wide |
+
+### Max-width containers
+
+| Use case | Recommended max-width |
+|----------|-----------------------|
+| Marketing / landing pages | `max-w-5xl` (1024px) or `max-w-6xl` (1152px) |
+| Application layouts | `max-w-7xl` (1280px) |
+| Reading / article content | `max-w-2xl` (672px) or `max-w-3xl` (768px) |
+| Full-bleed dashboards | None (use grid with sidebars) |
+
+---
+
+## Container Query Usage
+
+Use `@container` when a component's layout depends on its parent width, not the viewport.
+
+| Scenario | Use viewport breakpoint | Use container query |
+|----------|------------------------|---------------------|
+| Page-level layout | Yes | No |
+| Component in sidebar vs main | No | Yes |
+| Card grid columns | No | Yes |
+| Navbar collapsing | Yes | No |

package/skills/user-personas/SKILL.md

@@ -1,75 +1,75 @@
----
-name: user-personas
-tier: standard
-description: "Create refined user personas from research data — 3 personas with JTBD, pains, gains, and unexpected insights."
-triggers: [persona, user persona, user profile, user segment, user research]
-priority: 50
-chain-next: [create-prd, prioritization-frameworks]
----
-
-# User Personas
-
-> Based on the user persona framework from [Product Compass](https://www.productcompass.pm/p/interviewing-customers-the-ultimate) by Pawel Huryn (MIT License).
-
-## Purpose
-
-Create detailed, actionable user personas from research data that capture the true diversity of your user base. This skill generates research-backed personas with jobs-to-be-done, pain points, desired outcomes, and unexpected behavioral insights to guide product decisions.
-
-## Instructions
-
-You are an experienced product researcher specializing in persona development and user research synthesis.
-
-### Input
-
-Your task is to create 3 refined user personas for **$ARGUMENTS**.
-
-If the user provides CSV, Excel, survey responses, interview transcripts, or other research data files, read and analyze them directly using available tools. Extract key patterns, demographics, motivations, and behaviors.
-
-### Analysis Steps (Think Step by Step)
-
-1. **Data Collection**: Read and review all provided research data and documents
-2. **Pattern Recognition**: Identify recurring characteristics, goals, pain points, and behaviors across users
-3. **Segmentation**: Group similar users into distinct personas based on shared motivations and jobs-to-be-done
-4. **Enrichment**: For each persona, synthesize data into a coherent profile
-5. **Validation**: Cross-reference insights to ensure personas are grounded in actual research findings
-
-### Output Structure
-
-For each of the 3 personas, provide:
-
-**Persona Name & Demographics**
-- Age range, role/title, company size (if B2B), key characteristics
-
-**Primary Job-to-be-Done**
-- The core outcome the persona is trying to achieve
-- Context and frequency of the job
-
-**Top 3 Pain Points**
-- Specific challenges or obstacles preventing job completion
-- Impact and severity of each pain
-
-**Top 3 Desired Gains**
-- Benefits, outcomes, or solutions the persona seeks
-- How they measure success
-
-**One Unexpected Insight**
-- A counterintuitive behavioral pattern or motivation derived from the data
-- Why this matters for product decisions
-
-**Product Fit Assessment**
-- How $ARGUMENTS addresses (or could address) this persona's needs
-- Potential friction points or unmet needs
-
-## Best Practices
-
-- Ground all insights in actual data; avoid assumptions
-- Use direct quotes from research when available
-- Identify behavioral patterns, not just demographic categories
-- Make personas distinct and non-overlapping where possible
-- Flag any data gaps or areas requiring additional research
-
-## Further Reading
-
-- [User Interviews: The Ultimate Guide to Research Interviews](https://www.productcompass.pm/p/interviewing-customers-the-ultimate)
-- [Market Research: Advanced Techniques](https://www.productcompass.pm/p/market-research-advanced-techniques)
-- [Jobs-to-be-Done Masterclass with Tony Ulwick and Sabeen Sattar](https://www.productcompass.pm/p/jobs-to-be-done-masterclass-with)
+---
+name: user-personas
+tier: standard
+description: "Create refined user personas from research data — 3 personas with JTBD, pains, gains, and unexpected insights."
+triggers: [persona, user persona, user profile, user segment, user research]
+priority: 50
+chain-next: [create-prd, prioritization-frameworks]
+---
+
+# User Personas
+
+> Based on the user persona framework from [Product Compass](https://www.productcompass.pm/p/interviewing-customers-the-ultimate) by Pawel Huryn (MIT License).
+
+## Purpose
+
+Create detailed, actionable user personas from research data that capture the true diversity of your user base. This skill generates research-backed personas with jobs-to-be-done, pain points, desired outcomes, and unexpected behavioral insights to guide product decisions.
+
+## Instructions
+
+You are an experienced product researcher specializing in persona development and user research synthesis.
+
+### Input
+
+Your task is to create 3 refined user personas for **$ARGUMENTS**.
+
+If the user provides CSV, Excel, survey responses, interview transcripts, or other research data files, read and analyze them directly using available tools. Extract key patterns, demographics, motivations, and behaviors.
+
+### Analysis Steps (Think Step by Step)
+
+1. **Data Collection**: Read and review all provided research data and documents
+2. **Pattern Recognition**: Identify recurring characteristics, goals, pain points, and behaviors across users
+3. **Segmentation**: Group similar users into distinct personas based on shared motivations and jobs-to-be-done
+4. **Enrichment**: For each persona, synthesize data into a coherent profile
+5. **Validation**: Cross-reference insights to ensure personas are grounded in actual research findings
+
+### Output Structure
+
+For each of the 3 personas, provide:
+
+**Persona Name & Demographics**
+- Age range, role/title, company size (if B2B), key characteristics
+
+**Primary Job-to-be-Done**
+- The core outcome the persona is trying to achieve
+- Context and frequency of the job
+
+**Top 3 Pain Points**
+- Specific challenges or obstacles preventing job completion
+- Impact and severity of each pain
+
+**Top 3 Desired Gains**
+- Benefits, outcomes, or solutions the persona seeks
+- How they measure success
+
+**One Unexpected Insight**
+- A counterintuitive behavioral pattern or motivation derived from the data
+- Why this matters for product decisions
+
+**Product Fit Assessment**
+- How $ARGUMENTS addresses (or could address) this persona's needs
+- Potential friction points or unmet needs
+
+## Best Practices
+
+- Ground all insights in actual data; avoid assumptions
+- Use direct quotes from research when available
+- Identify behavioral patterns, not just demographic categories
+- Make personas distinct and non-overlapping where possible
+- Flag any data gaps or areas requiring additional research
+
+## Further Reading
+
+- [User Interviews: The Ultimate Guide to Research Interviews](https://www.productcompass.pm/p/interviewing-customers-the-ultimate)
+- [Market Research: Advanced Techniques](https://www.productcompass.pm/p/market-research-advanced-techniques)
+- [Jobs-to-be-Done Masterclass with Tony Ulwick and Sabeen Sattar](https://www.productcompass.pm/p/jobs-to-be-done-masterclass-with)

package/skills/user-personas/rubrics/research-methods.md

@@ -1,56 +1,56 @@
-# Persona Research Methodology
-
-## Research Method Selection
-
-| Situation | Recommended Method | Sample Size |
-|-----------|-------------------|-------------|
-| New product, no users yet | Exploratory interviews | 8–12 participants |
-| Existing product, need depth | In-depth interviews | 5–8 per segment |
-| Validating existing personas | Survey | 50+ respondents |
-| Behavioral patterns | Analytics + session recordings | All available data |
-| Competitive landscape | Competitor review + job forums | Qualitative |
-
-## Interview Design Checklist
-
-- [ ] Questions focus on past behavior, not hypothetical future behavior
-- [ ] "Tell me about a time when..." used instead of "Would you...?"
-- [ ] No leading questions (avoid "Don't you find X frustrating?")
-- [ ] Follow-up probes prepared: "Why?", "What happened next?", "How did that make you feel?"
-- [ ] Job-to-be-done lens: ask what they're trying to accomplish, not what features they want
-- [ ] Session recorded (with consent) for later synthesis
-- [ ] Duration: 45–60 minutes per interview
-
-## Data Collection Quality Gates
-
-- [ ] Minimum 5 interviews per distinct segment before drawing conclusions
-- [ ] Direct quotes captured verbatim (not paraphrased during interview)
-- [ ] Demographic bias checked — sample matches target market
-- [ ] B2B: multiple roles interviewed (buyer, user, influencer)
-- [ ] Negative cases included — interview users who churned or rejected the product
-
-## Synthesis Process
-
-1. **Affinity mapping**: Group raw observations by theme (not by participant)
-2. **Pattern extraction**: Identify recurring pain points and jobs across 3+ participants
-3. **Segmentation**: Cluster participants by shared motivations (not demographics)
-4. **Persona drafting**: One persona per distinct motivation cluster
-5. **Validation**: Cross-reference each persona claim against source data
-
-## Persona Validity Checklist
-
-- [ ] Each persona grounded in ≥3 real participants from research
-- [ ] Personas are mutually distinct — overlapping personas should be merged
-- [ ] Unexpected insights included — if all insights are obvious, dig deeper
-- [ ] Demographics are secondary — job-to-be-done drives persona definition
-- [ ] Quotes used are verbatim from research (not invented)
-- [ ] Data gaps explicitly flagged — don't fill gaps with assumptions
-
-## Common Research Mistakes
-
-| Mistake | Consequence | Fix |
-|---------|-------------|-----|
-| Asking "what features do you want?" | Users design solutions, not needs | Ask about current behavior and pain |
-| Only interviewing enthusiasts | Survivorship bias | Include churned users and non-adopters |
-| Conflating segment with persona | Personas become stereotypes | Base personas on motivations, not age/gender |
-| Too many personas (>5) | Team ignores them | Merge overlapping clusters, max 3–4 |
-| No data gaps acknowledged | False confidence | Flag what you don't yet know |
+# Persona Research Methodology
+
+## Research Method Selection
+
+| Situation | Recommended Method | Sample Size |
+|-----------|-------------------|-------------|
+| New product, no users yet | Exploratory interviews | 8–12 participants |
+| Existing product, need depth | In-depth interviews | 5–8 per segment |
+| Validating existing personas | Survey | 50+ respondents |
+| Behavioral patterns | Analytics + session recordings | All available data |
+| Competitive landscape | Competitor review + job forums | Qualitative |
+
+## Interview Design Checklist
+
+- [ ] Questions focus on past behavior, not hypothetical future behavior
+- [ ] "Tell me about a time when..." used instead of "Would you...?"
+- [ ] No leading questions (avoid "Don't you find X frustrating?")
+- [ ] Follow-up probes prepared: "Why?", "What happened next?", "How did that make you feel?"
+- [ ] Job-to-be-done lens: ask what they're trying to accomplish, not what features they want
+- [ ] Session recorded (with consent) for later synthesis
+- [ ] Duration: 45–60 minutes per interview
+
+## Data Collection Quality Gates
+
+- [ ] Minimum 5 interviews per distinct segment before drawing conclusions
+- [ ] Direct quotes captured verbatim (not paraphrased during interview)
+- [ ] Demographic bias checked — sample matches target market
+- [ ] B2B: multiple roles interviewed (buyer, user, influencer)
+- [ ] Negative cases included — interview users who churned or rejected the product
+
+## Synthesis Process
+
+1. **Affinity mapping**: Group raw observations by theme (not by participant)
+2. **Pattern extraction**: Identify recurring pain points and jobs across 3+ participants
+3. **Segmentation**: Cluster participants by shared motivations (not demographics)
+4. **Persona drafting**: One persona per distinct motivation cluster
+5. **Validation**: Cross-reference each persona claim against source data
+
+## Persona Validity Checklist
+
+- [ ] Each persona grounded in ≥3 real participants from research
+- [ ] Personas are mutually distinct — overlapping personas should be merged
+- [ ] Unexpected insights included — if all insights are obvious, dig deeper
+- [ ] Demographics are secondary — job-to-be-done drives persona definition
+- [ ] Quotes used are verbatim from research (not invented)
+- [ ] Data gaps explicitly flagged — don't fill gaps with assumptions
+
+## Common Research Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Asking "what features do you want?" | Users design solutions, not needs | Ask about current behavior and pain |
+| Only interviewing enthusiasts | Survivorship bias | Include churned users and non-adopters |
+| Conflating segment with persona | Personas become stereotypes | Base personas on motivations, not age/gender |
+| Too many personas (>5) | Team ignores them | Merge overlapping clusters, max 3–4 |
+| No data gaps acknowledged | False confidence | Flag what you don't yet know |