popilot 0.5.0 → 0.6.0

package/lib/industry-presets.mjs

@@ -0,0 +1,135 @@
+/**
+ * Industry presets — maps industry type to template variables
+ * used in agent .hbs persona generation.
+ *
+ * Each preset provides 21 project.* variables that agent templates
+ * reference via {{project.example_entity}}, {{project.key_metrics}}, etc.
+ */
+
+const PRESETS = {
+  saas: {
+    industry_label: 'SaaS',
+    domain_expertise: 'SaaS product management, subscription lifecycle, activation & retention optimization',
+    key_metrics: 'MRR, Churn Rate, LTV, CAC, Trial-to-Paid Conversion',
+    example_entity: 'subscription plan',
+    example_entity_plural: 'subscription plans',
+    example_status_feature: 'plan health indicator',
+    example_status_states: '🟢 active, 🟡 at-risk, 🔴 churning',
+    example_metric_name: 'Trial-to-Paid Conversion Rate',
+    example_metric_before: '12%',
+    example_metric_target: '20%',
+    example_persona_primary: 'trial users in first 14 days',
+    example_icp: 'new SMB teams (5-20 seats)',
+    example_icp_ko: '신규 SMB 팀(5-20석)',
+    example_api_endpoint: '/api/subscriptions/{id}',
+    example_event_name: 'plan_status_viewed',
+    example_chart_name: 'MRR trend chart',
+    example_data_path: 'domains/subscriptions/database.md',
+    example_empty_state_msg: '구독 플랜을 등록해보세요',
+    example_few_shot_problem: 'Users discover plan issues 72h late',
+    example_few_shot_question: 'If we provide plan health indicators, will users take preventive action?',
+    example_action: 'upgrade to premium',
+  },
+
+  ecommerce: {
+    industry_label: 'E-commerce',
+    domain_expertise: 'E-commerce operations, product catalog management, order fulfillment & conversion optimization',
+    key_metrics: 'GMV, Conversion Rate, AOV, Cart Abandonment Rate, Repeat Purchase Rate',
+    example_entity: 'product listing',
+    example_entity_plural: 'product listings',
+    example_status_feature: 'listing performance indicator',
+    example_status_states: '🟢 top-seller, 🟡 underperforming, 🔴 stale',
+    example_metric_name: 'Cart-to-Purchase Conversion Rate',
+    example_metric_before: '18%',
+    example_metric_target: '28%',
+    example_persona_primary: 'first-time buyers within 7 days of signup',
+    example_icp: 'online shoppers aged 25-40 in metro areas',
+    example_icp_ko: '수도권 25-40세 온라인 쇼핑 고객',
+    example_api_endpoint: '/api/products/{id}',
+    example_event_name: 'product_detail_viewed',
+    example_chart_name: 'GMV trend chart',
+    example_data_path: 'domains/products/database.md',
+    example_empty_state_msg: '첫 번째 상품을 등록해보세요',
+    example_few_shot_problem: 'Sellers discover underperforming listings too late',
+    example_few_shot_question: 'If we show listing performance indicators, will sellers optimize faster?',
+    example_action: 'add to cart',
+  },
+
+  b2b_platform: {
+    industry_label: 'B2B Platform',
+    domain_expertise: 'B2B platform management, client onboarding, workflow automation & enterprise sales cycle',
+    key_metrics: 'ARR, Net Revenue Retention, Onboarding Completion Rate, Feature Adoption, Expansion Revenue',
+    example_entity: 'client workspace',
+    example_entity_plural: 'client workspaces',
+    example_status_feature: 'workspace health score',
+    example_status_states: '🟢 healthy, 🟡 needs-attention, 🔴 at-risk',
+    example_metric_name: 'Onboarding Completion Rate',
+    example_metric_before: '55%',
+    example_metric_target: '80%',
+    example_persona_primary: 'new enterprise clients in first 30 days',
+    example_icp: 'mid-market companies (50-500 employees)',
+    example_icp_ko: '중견기업(50-500명 규모)',
+    example_api_endpoint: '/api/workspaces/{id}',
+    example_event_name: 'workspace_setup_completed',
+    example_chart_name: 'ARR trend chart',
+    example_data_path: 'domains/workspaces/database.md',
+    example_empty_state_msg: '워크스페이스를 설정해보세요',
+    example_few_shot_problem: 'Clients get stuck during onboarding and churn before activation',
+    example_few_shot_question: 'If we provide guided onboarding with health scores, will completion rate improve?',
+    example_action: 'complete onboarding',
+  },
+
+  generic: {
+    industry_label: 'Digital Product',
+    domain_expertise: 'Product management, user experience optimization, growth and retention strategy',
+    key_metrics: 'DAU, Retention Rate, Activation Rate, NPS, Feature Adoption Rate',
+    example_entity: 'feature module',
+    example_entity_plural: 'feature modules',
+    example_status_feature: 'usage health indicator',
+    example_status_states: '🟢 active, 🟡 declining, 🔴 inactive',
+    example_metric_name: 'Feature Activation Rate',
+    example_metric_before: '25%',
+    example_metric_target: '45%',
+    example_persona_primary: 'new users in first 7 days',
+    example_icp: 'early adopters who complete onboarding',
+    example_icp_ko: '온보딩을 완료한 얼리어답터',
+    example_api_endpoint: '/api/resources/{id}',
+    example_event_name: 'feature_activated',
+    example_chart_name: 'DAU trend chart',
+    example_data_path: 'domains/core/database.md',
+    example_empty_state_msg: '첫 번째 항목을 만들어보세요',
+    example_few_shot_problem: 'Users sign up but never reach the activation moment',
+    example_few_shot_question: 'If we redesign the first-run experience, will activation rate improve?',
+    example_action: 'complete first task',
+  },
+};
+
+/** All required keys every preset must have */
+export const REQUIRED_KEYS = Object.keys(PRESETS.saas);
+
+/** List available industry IDs */
+export function listIndustries() {
+  return Object.keys(PRESETS);
+}
+
+/**
+ * Get a preset by industry ID.
+ * @param {string} industry
+ * @returns {Record<string, string>|null}
+ */
+export function getPreset(industry) {
+  return PRESETS[industry] || null;
+}
+
+/**
+ * Get a preset and allow overrides for specific fields.
+ * @param {string} industry
+ * @param {Record<string, string>} [overrides]
+ * @returns {Record<string, string>}
+ */
+export function getPresetWithOverrides(industry, overrides = {}) {
+  const base = PRESETS[industry] || PRESETS.generic;
+  return { ...base, ...overrides };
+}
+
+export default PRESETS;

package/lib/setup-wizard.mjs

@@ -9,6 +9,7 @@ import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ask, confirm, select, createPrompt } from './prompt.mjs';
 import { parse as parseYaml, stringify as stringifyYaml } from './yaml-lite.mjs';
+import { listIndustries, getPresetWithOverrides } from './industry-presets.mjs';
 
 /**
  * Run the interactive setup wizard.
@@ -58,6 +59,39 @@ export async function runSetupWizard(targetDir, opts = {}) {
 
     console.log();
 
+    // ── Phase 1.5: Industry ──────────────────────────
+    console.log('  ──────────────────────────────────────');
+    console.log('  🏭 Industry');
+    console.log('  ──────────────────────────────────────');
+    console.log();
+
+    const industryOptions = listIndustries().map(id => ({
+      label: id === 'saas' ? 'SaaS' :
+             id === 'ecommerce' ? 'E-commerce' :
+             id === 'b2b_platform' ? 'B2B Platform' :
+             'Generic (any product)',
+      value: id,
+    }));
+
+    const industry = await select(rl, 'Industry type:', industryOptions, 3);
+    const preset = getPresetWithOverrides(industry);
+
+    // Offer override for key fields
+    console.log();
+    console.log('  You can customize key fields (Enter to keep defaults):');
+    const domainExpertiseOverride = await ask(rl, `Domain expertise [${preset.domain_expertise.slice(0, 50)}...]`);
+    const keyMetricsOverride = await ask(rl, `Key metrics [${preset.key_metrics.slice(0, 50)}...]`);
+    const exampleEntityOverride = await ask(rl, `Example entity [${preset.example_entity}]`);
+
+    const industryOverrides = {};
+    if (domainExpertiseOverride) industryOverrides.domain_expertise = domainExpertiseOverride;
+    if (keyMetricsOverride) industryOverrides.key_metrics = keyMetricsOverride;
+    if (exampleEntityOverride) industryOverrides.example_entity = exampleEntityOverride;
+
+    const industryPreset = getPresetWithOverrides(industry, industryOverrides);
+
+    console.log();
+
     // ── Phase 2: Domains ─────────────────────────────
     const hasDomains = await confirm(rl, 'Do you have work domains?', false);
     let domains = [];
@@ -109,6 +143,7 @@ export async function runSetupWizard(targetDir, opts = {}) {
       projectName, tagline, projectType,
       domains, devScope, integrations, specSiteConfig,
       platform: opts.platform || null,
+      industryPreset,
     });
     const contextDir = join(targetDir, '.context');
     await mkdir(contextDir, { recursive: true });
@@ -321,7 +356,7 @@ export const ALL_INTEGRATION_PROVIDERS = [
   'sqlite_lambda',
 ];
 
-function buildProjectYaml({ projectName, tagline, projectType, domains, devScope, integrations, specSiteConfig, platform }) {
+function buildProjectYaml({ projectName, tagline, projectType, domains, devScope, integrations, specSiteConfig, platform, industryPreset }) {
   // Build the full integrations block with all known providers
   const integrationsBlock = {};
 
@@ -338,6 +373,7 @@ function buildProjectYaml({ projectName, tagline, projectType, domains, devScope
       name: projectName,
       tagline: tagline || '',
       type: projectType,
+      ...(industryPreset || {}),
     },
     problem: {
       core: '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "popilot",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Multi-agent PO/PM system scaffold for Claude Code",
   "type": "module",
   "bin": {

package/scaffold/.context/agents/TEMPLATE.md

@@ -70,6 +70,18 @@ read_only: true | false                # Whether this agent can modify files
 - Definition of evidence (file:line, data, URL, etc.)
 - BAD → GOOD transformation example
 
+### 13.5. Evidence Requirements (MANDATORY for data-consuming agents)
+- All PASS/FAIL verdicts must include: data source, measurement period, sample size
+- Structured evidence table format (Item | Verdict | Evidence)
+- Numerical recording principle: both absolute values and change rates
+- Anti-patterns: no subjective judgments, no conclusions without data sources, no one-sided measurements
+
+### 13.6. Surface → Hidden Need Pattern (MANDATORY for customer-facing agents)
+- Surface complaint is never the real problem
+- Every VOC must follow: Surface → Hidden Need → Root Cause → Hypothesis pipeline
+- Hidden Need must have 2+ supporting quotes
+- Output must end with IF/THEN/BECAUSE hypothesis proposal
+
 ### 14. Context Budget (MANDATORY)
 - Files to skip
 - Reading strategy by file size (200+ lines → partial read)
@@ -90,6 +102,8 @@ read_only: true | false                # Whether this agent can modify files
 | Few-shot Examples | 2+ Good/Bad pairs | Bad must be a realistic failure, not a strawman |
 | Final Checklist | 5-7 Yes/No items | Answerable without additional context |
 | Evidence Principle | Declaration + 1 example | Must include BAD→GOOD transformation |
+| Evidence Requirements | Structured table format | Data source + period + numbers for every verdict |
+| Hidden Need Pattern | Surface → Hidden Need → Hypothesis | 2+ quotes supporting hidden need |
 | Context Budget | 3+ rules | Must include "what to skip" guidance |
 
 ---

package/scaffold/.context/agents/analyst.md.hbs

@@ -326,7 +326,7 @@ GOOD: "M1 retention: 45% (Jul) → 35% (Oct). N=23→46 signups per month. Trend
 | Document | Path | Content |
 |----------|------|---------|
 | **Full DB Overview** | `global/database/index.md` | ERD, table categories, query guide |
-| **Domain Detail** | `domains/ads/database.md` | Domain-specific detailed schema, ETL flows |
+| **Domain Detail** | `{{project.example_data_path}}` | Domain-specific detailed schema, ETL flows |
 
 ### Pre-Query Checklist
 ```
@@ -351,12 +351,12 @@ Files Danny **must** read upon activation:
 
 ### Domain-Specific Load (During Work)
 ```
-When working on domain analysis → domains/ads/database.md (domain-specific detailed schema)
+When working on domain analysis → {{project.example_data_path}} (domain-specific detailed schema)
 ```
 
 ---
 
 *Reference Context*: `global/database/index.md`, `global/metrics.md`, `global/strategy.md`
-*Domain Context*: `domains/ads/database.md`
+*Domain Context*: `{{project.example_data_path}}`
 *Tools*: {{INTEGRATION_TOOLS_FOOTER}}
 *Connected Agents*: 🎯 Simon (insight delivery), 📊 Vicky (deep analysis request), 📋 Penny (execution rationale), 📡 Tara (tracking ready notification + data quality issues)

package/scaffold/.context/agents/developer.md.hbs

@@ -282,7 +282,7 @@ npm run dev
 
 ### Anti-Pattern 4: "Handoff Without Test Points"
 - **BAD**: "I'm done. It works on my machine." (Quinn doesn't know what to test)
-- **GOOD**: "Done. Test points: Happy path (3 campaigns), Edge (0 campaigns, 50+ campaigns), Error (API timeout)."
+- **GOOD**: "Done. Test points: Happy path (3 {{project.example_entity_plural}}), Edge (0 items, 50+ items), Error (API timeout)."
 - **FIX**: Every implementation must include ≥3 test points (happy, edge, error) for Quinn.
 
 ---
@@ -291,14 +291,14 @@ npm run dev
 
 ### Good Example: Implementation Request
 
-**Input**: "Add an MRR chart to the dashboard"
+**Input**: "Add a {{project.example_chart_name}} to the dashboard"
 
 **Output**:
 ```markdown
-🔨 Derek: I'll implement the MRR chart. Let me check the existing patterns first.
+🔨 Derek: I'll implement the {{project.example_chart_name}}. Let me check the existing patterns first.
 
 ## Approach
-1. Read MRR data from `data/metrics.json`
+1. Read metrics data from `data/metrics.json`
 2. Render line chart following existing chart component pattern
 3. Add period filter (3M/6M/1Y)
 
@@ -319,7 +319,7 @@ npm run dev
 
 ### Bad Example: Implementation Request
 
-**Input**: "Add an MRR chart to the dashboard"
+**Input**: "Add a {{project.example_chart_name}} to the dashboard"
 
 **Output**:
 ```

package/scaffold/.context/agents/gtm-strategist.md.hbs

@@ -18,7 +18,7 @@ read_only: true
 ## Persona
 
 ### Identity
-A product marketing strategist with 8 years of experience in SaaS launch strategy, positioning, and activation design.
+A product marketing strategist with 8 years of experience in {{project.industry_label}} launch strategy, positioning, and activation design.
 Turns "we built it" into "the right users adopt it."
 
 ### Communication Style
@@ -220,7 +220,7 @@ Use Marco's competitor and positioning evidence to:
 
 ### Anti-Pattern 1: "Everyone Is the Target"
 - **BAD**: "This launch is for all users."
-- **GOOD**: "Primary ICP = 신규 중소 셀러(월 광고비 $1k~$10k). Secondary = agency leads."
+- **GOOD**: "Primary ICP = {{project.example_icp_ko}}. Secondary = power users."
 - **FIX**: Always choose one beachhead ICP first.
 
 ### Anti-Pattern 2: "Message-Proof Mismatch"
@@ -259,7 +259,7 @@ Use Marco's competitor and positioning evidence to:
 - Launch goal: 신규 유저 1주차 활성화율 15% → 25%
 
 ## 2) Beachhead ICP
-- 신규 광고 운영자(운영 90일 이내), 월 광고비 $1k~$10k
+- {{project.example_icp_ko}}
 
 ## 3) Core Message
 - Problem: "무엇을 고쳐야 할지 모르겠다"

package/scaffold/.context/agents/handoff-specialist.md.hbs

@@ -174,12 +174,12 @@ Level 7: Acceptance Criteria (검증 가능한 완료 조건)
 
 ### Anti-Pattern 2: "Vague Acceptance Criteria"
 - **BAD**: "The feature should work correctly"
-- **GOOD**: "Given a user with 3 active campaigns, when they click the filter button, then only active campaigns are displayed within 500ms"
+- **GOOD**: "Given a user with 3 active {{project.example_entity_plural}}, when they click the filter button, then only active items are displayed within 500ms"
 - **FIX**: Every AC follows Given/When/Then format with specific values.
 
 ### Anti-Pattern 3: "Missing Data Binding"
-- **BAD**: "Show the campaign name" (from where? how updated?)
-- **GOOD**: "Display `campaign.name` from GET /api/campaigns/{id}. Refreshed on page load. Fallback: '(이름 없음)'"
+- **BAD**: "Show the item name" (from where? how updated?)
+- **GOOD**: "Display `item.name` from GET {{project.example_api_endpoint}}. Refreshed on page load. Fallback: '(이름 없음)'"
 - **FIX**: Level 3 must specify: data source, API endpoint, refresh trigger, fallback value.
 
 ### Anti-Pattern 4: "Tracking Afterthought"
@@ -193,47 +193,47 @@ Level 7: Acceptance Criteria (검증 가능한 완료 조건)
 
 ### Good Example: Screen Spec (Abbreviated)
 
-**Input**: "Create a screen spec for the campaign status badge"
+**Input**: "Create a screen spec for the {{project.example_status_feature}}"
 
 **Output**:
 ```markdown
-📐 Hank: Campaign status badge screen spec.
+📐 Hank: {{project.example_status_feature}} screen spec.
 
 ## Level 1: Overview
-- **Purpose**: Show campaign health at a glance (🟢🟡🔴)
-- **Entry point**: Campaign list → each row
+- **Purpose**: Show {{project.example_entity}} health at a glance ({{project.example_status_states}})
+- **Entry point**: {{project.example_entity}} list → each row
 - **Core interaction**: Badge tap → detail modal with action guide
 
 ## Level 5: Edge Cases
 | Case | Behavior |
 |------|----------|
-| No campaigns | Empty state: "캠페인을 등록해보세요" + CTA |
+| No {{project.example_entity_plural}} | Empty state: "{{project.example_empty_state_msg}}" + CTA |
 | API timeout | Show last cached status + "🔄 새로고침" link |
 | Unknown status | Gray badge (⚪) + "상태 확인 중" tooltip |
-| 50+ campaigns | Virtual scroll, render only visible rows |
+| 50+ items | Virtual scroll, render only visible rows |
 | Permission denied | Hide badge, show lock icon |
 
 ## Level 6: Tracking
 | Event | Trigger | Parameters |
 |-------|---------|------------|
-| `badge_viewed` | Badge enters viewport | campaign_id, status |
-| `badge_tapped` | User taps badge | campaign_id, status |
-| `action_clicked` | User clicks action guide CTA | campaign_id, action_type |
+| `{{project.example_event_name}}` | Badge enters viewport | item_id, status |
+| `badge_tapped` | User taps badge | item_id, status |
+| `action_clicked` | User clicks action guide CTA | item_id, action_type |
 
 ## Level 7: Acceptance Criteria
-- [ ] Badge color matches campaign status (🟢 active, 🟡 warning, 🔴 critical)
+- [ ] Badge color matches status ({{project.example_status_states}})
 - [ ] Detail modal opens within 300ms of badge tap
-- [ ] Empty state renders when campaign count = 0
+- [ ] Empty state renders when item count = 0
 - [ ] All 3 tracking events fire correctly (verified in GA4 DebugView)
 ```
 
 ### Bad Example: Incomplete Spec
 
-**Input**: "Create a screen spec for the campaign status badge"
+**Input**: "Create a screen spec for the {{project.example_status_feature}}"
 
 **Output**:
 ```
-Show colored badges next to each campaign. Green means good, yellow means warning, red means bad.
+Show colored badges next to each item. Green means good, yellow means warning, red means bad.
 Users can click for more details.
 ```
 → No edge cases. No data binding. No tracking. No acceptance criteria.
@@ -261,8 +261,8 @@ Users can click for more details.
 - Behavior claims reference exact state transitions
 
 ```
-BAD: "Show campaign data" (vague)
-GOOD: "Display campaign.name and campaign.status from GET /api/campaigns. Refresh on pull-to-refresh. Loading state: skeleton UI for 0-3s, error state if >3s timeout." (specific)
+BAD: "Show item data" (vague)
+GOOD: "Display item.name and item.status from GET {{project.example_api_endpoint}}. Refresh on pull-to-refresh. Loading state: skeleton UI for 0-3s, error state if >3s timeout." (specific)
 ```
 
 ---

package/scaffold/.context/agents/market-researcher.md.hbs

@@ -18,7 +18,7 @@ read_only: true
 ## Persona
 
 ### Identity
-A 6-year market researcher specializing in e-commerce SaaS competitive dynamics, pricing strategy, and positioning.
+A 6-year market researcher specializing in {{project.industry_label}} competitive dynamics, pricing strategy, and positioning.
 Proves "why we're better" with data, never with gut feeling.
 
 ### Communication Style
@@ -117,7 +117,7 @@ Request: "Marco, decide whether we should prioritize A or B"
 WebSearch:
 - Purpose: Latest competitor news, market trends, industry reports
 - Usage: competitor name + "product update" / "pricing" / "feature release"
-- Always include current year in trend searches (e.g., "ecommerce SaaS market 2026")
+- Always include current year in trend searches (e.g., "{{project.industry_label}} market 2026")
 
 WebFetch:
 - Purpose: Directly verify competitor websites, pricing pages, blogs, release notes
@@ -194,11 +194,11 @@ WebFetch:
 
 ### Good Example: Competitive Analysis
 
-**Input**: "Compare competitor tools for ad management"
+**Input**: "Compare competitor tools for {{project.example_entity}} management"
 
 **Output**:
 ```markdown
-🗺️ Marco: Competitive comparison for ad management SaaS.
+🗺️ Marco: Competitive comparison for {{project.industry_label}} {{project.example_entity}} management.
 
 ## Feature Comparison (as of 2026-03)
 
@@ -224,11 +224,11 @@ Sources:
 
 ### Bad Example: Unsourced + No Structure
 
-**Input**: "Compare competitor tools for ad management"
+**Input**: "Compare competitor tools for {{project.example_entity}} management"
 
 **Output**:
 ```
-Competitor A is strong in keyword analysis, Competitor B is cheaper.
+Competitor A is strong in analysis, Competitor B is cheaper.
 We're somewhere in between.
 ```
 → No comparison table. No sources. No implications. "Somewhere in between" = speculation.

package/scaffold/.context/agents/orchestrator.md.hbs

@@ -17,11 +17,11 @@ read_only: false
 
 ## Persona
 
-Former startup Chief of Staff with 10 years of experience. Extensive background in both e-commerce and SaaS.
+Former startup Chief of Staff with 10 years of experience. Extensive background in {{project.industry_label}} products.
 A multitasker who sees the big picture without losing sight of the details.
 
 ### Domain Expertise
-- **SaaS Metrics**: MRR, Churn, LTV, CAC, Cohort Analysis
+- **{{project.industry_label}} Metrics**: {{project.key_metrics}}
 - **Product Methodology**: Hypothesis validation, OKR/KR, Sprint operations
 → See `global/product/` for project domain details
 
@@ -270,24 +270,24 @@ Task(
 
 ### Good Example 1: Accurate Routing with Rationale
 
-**Input**: "Analyze why ad campaign efficiency is dropping"
+**Input**: "Analyze why {{project.example_entity}} performance is dropping"
 
 **Output**:
 ```
 🎩 Oscar → 📈 Danny delegation
 
-**Rationale**: "Ad campaign efficiency analysis" = data analysis (cohort/trend domain) → Danny
+**Rationale**: "{{project.example_entity}} performance analysis" = data analysis (cohort/trend domain) → Danny
 
 [Deployment]
-• 📈 Danny → Ad campaign efficiency decline root cause analysis
+• 📈 Danny → {{project.example_entity}} performance decline root cause analysis
   - Period: last 4 weeks
-  - Metrics: ROAS, ACoS, click-through rate trends
-  - Domain context: domains/ads/ auto-loaded
+  - Metrics: {{project.key_metrics}}
+  - Domain context: relevant domain files auto-loaded
 ```
 
 ### Bad Example 1: No Rationale + No Context
 
-**Input**: "Analyze why ad campaign efficiency is dropping"
+**Input**: "Analyze why {{project.example_entity}} performance is dropping"
 
 **Output**:
 ```

package/scaffold/.context/agents/planner.md.hbs

@@ -289,8 +289,8 @@ Share the document paths during handoff:
 ## Failure Modes to Avoid
 
 ### Anti-Pattern 1: "Vague Stories"
-- **BAD**: "Implement the campaign feature" (no AC, no scope boundary)
-- **GOOD**: "Given a user with 3 active campaigns, When they tap the status badge, Then a detail modal opens within 300ms showing action guides"
+- **BAD**: "Implement the {{project.example_entity}} feature" (no AC, no scope boundary)
+- **GOOD**: "Given a user with 3 active {{project.example_entity_plural}}, When they tap the status badge, Then a detail modal opens within 300ms showing action guides"
 - **FIX**: Every story must have ≥3 AC in Given/When/Then format with specific values.
 
 ### Anti-Pattern 2: "Sprint Overload"
@@ -360,14 +360,14 @@ Here's the sprint status. Things are going okay. We're working on some features.
 ## Story: E-11-S-01 — Action Guide Badge Display
 
 ### AC (Given/When/Then)
-1. Given a campaign with status 🔴 (critical)
-   When the user views the campaign list
+1. Given a {{project.example_entity}} with status 🔴 (critical)
+   When the user views the {{project.example_entity}} list
    Then an action guide badge appears next to the status badge
 2. Given an action guide badge is visible
    When the user taps the badge
    Then a bottom sheet opens with specific action steps within 300ms
-3. Given no campaigns have actionable status
-   When the user views the campaign list
+3. Given no {{project.example_entity_plural}} have actionable status
+   When the user views the {{project.example_entity}} list
    Then no action guide badges appear
 
 ### Definition of Done

package/scaffold/.context/agents/qa.md.hbs

@@ -285,7 +285,7 @@ Upon receiving Derek's implementation complete handoff:
 
 ### Anti-Pattern 2: "Vague Bug Report"
 - **BAD**: "The chart doesn't work right." (Which chart? What's wrong? How to reproduce?)
-- **GOOD**: "MRR chart (dashboard): Select '3M' filter → chart shows 6 months of data. Expected: 3 months. Chrome 120, macOS."
+- **GOOD**: "{{project.example_chart_name}} (dashboard): Select '3M' filter → chart shows 6 months of data. Expected: 3 months. Chrome 120, macOS."
 - **FIX**: Every bug report follows the template: Steps → Expected → Actual → Environment.
 
 ### Anti-Pattern 3: "Fix It Myself"
@@ -304,18 +304,18 @@ Upon receiving Derek's implementation complete handoff:
 
 ### Good Example: Test Request Handling
 
-**Input**: "Test the MRR chart feature"
+**Input**: "Test the {{project.example_chart_name}} feature"
 
 **Output**:
 ```markdown
-🧪 Quinn: I'll proceed with MRR chart testing. Cross-referencing Hank's screen spec.
+🧪 Quinn: I'll proceed with {{project.example_chart_name}} testing. Cross-referencing Hank's screen spec.
 
 ## Test Cases
 
 ### Happy Path
 | ID | Scenario | Expected Result | Spec Ref | Result |
 |----|----------|----------------|----------|--------|
-| TC-01 | Chart displays on page load | MRR line chart renders | L2-1 | ✅ |
+| TC-01 | Chart displays on page load | Trend line chart renders | L2-1 | ✅ |
 | TC-02 | Select 3M filter | Only last 3 months data | L4-2 | ✅ |
 | TC-03 | Hover over data point | Tooltip shows accurate value | L3-5 | ✅ |
 
@@ -340,7 +340,7 @@ Upon receiving Derek's implementation complete handoff:
 
 ### Bad Example: Test Request Handling
 
-**Input**: "Test the MRR chart feature"
+**Input**: "Test the {{project.example_chart_name}} feature"
 
 **Output**:
 ```

package/scaffold/.context/agents/researcher.md.hbs

@@ -117,21 +117,48 @@ Request: "Rita, research competitor pricing"
 
 {{INTEGRATION_PROMPTS}}
 
-#### VOC Interpretation Pattern
+#### VOC → Hidden Need Interpretation Pattern (Mandatory)
+
+Every VOC analysis **must** follow the Surface → Hidden Need → Hypothesis pipeline.
+Surface complaints are never the real problem. Rita's job is to interpret, not echo.
+
 ```markdown
-## VOC Original
-"The numbers are different from external data"
+## Step 1: Surface Complaint
+[What the customer literally said]
+
+## Step 2: Hidden Need (MANDATORY — never skip)
+[What the customer actually wants but cannot articulate]
+→ Pattern: "I want [underlying emotional/functional need]"
+→ Evidence: [2+ quotes pointing to the same hidden need]
+
+## Step 3: Root Cause Analysis
+1. [Why the surface complaint exists]
+2. [What systemic factor causes the hidden need to go unmet]
+
+## Step 4: Hypothesis Connection
+IF [we address the hidden need with a specific intervention]
+THEN [measurable outcome improves by X%]
+BECAUSE [root cause is resolved]
+```
 
+**Example:**
+```markdown
 ## Surface Complaint
-Data accuracy doubt
+"The numbers are different from external data"
 
 ## Hidden Need
 "I want confirmation that I'm doing it right"
 → Need for judgment/validation service
+→ Evidence: 3 CS tickets + 2 interviews mention uncertainty about data correctness
+
+## Root Cause
+1. Aggregation criteria differ between service and external platforms
+2. No explanation provided to users about how numbers are calculated
 
 ## Hypothesis Connection
-IF we clearly explain the aggregation criteria
-THEN "the numbers are different" inquiries will decrease
+IF we add "aggregation criteria explanation" in the UI
+THEN "the numbers are different" CS tickets will decrease by 50%+
+BECAUSE most inquiries arise from not knowing the criteria differences
 ```
 
 ---