diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a1b7be99..3aa92738 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,8 +11,8 @@ "plugins": [ { "name": "compound-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 19 skills.", - "version": "2.34.0", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 30 specialized agents, 23 commands, and 22 skills.", + "version": "2.35.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..eca411a1 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "compound-engineering@every-marketplace": true + } +} diff --git a/.gitignore b/.gitignore index f8f7b971..7dc2ae43 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ node_modules/ .codex/ todos/ + +# Research data - transcripts contain raw interview data with PII +docs/research/transcripts/*.md diff --git a/docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md b/docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md new file mode 100644 index 00000000..8f1c84c1 --- /dev/null +++ b/docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md @@ -0,0 +1,342 @@ +# User Research Workflow for Compound Engineering + +**Date:** 2026-02-10 +**Status:** Brainstorm complete + +## What We're Building + +A user research workflow that closes the gap between research and implementation. Today, the compound engineering plugin has zero research capabilities — insights from user interviews sit in Google Docs and never reach the developer. This workflow makes research a first-class input to AI-assisted development. + +**Core flow:** Plan research -> Conduct interviews -> Store transcripts -> Process into insights -> Build personas -> Feed into feature planning + +**Artifacts live in:** `docs/research/` following existing YAML frontmatter patterns. + +**Methodology grounded in:** Teresa Torres' *Continuous Discovery Habits* (story-based interviewing, interview snapshots, Opportunity Solution Trees) and Rob Fitzpatrick's *The Mom Test* (past behavior over future speculation). See `references/discovery-playbook.md` bundled with the skills. + +**Shipped in two PRs:** +- **PR 1:** The research workflow command, three skills, agent, and directory structure +- **PR 2:** Integration with `/workflows:brainstorm` and `/workflows:plan` to auto-surface research + +## Why This Approach + +**Approach chosen: Research Workflow (full workflow command + modular skills + agent)** + +This mirrors the existing workflow pattern (`brainstorm -> plan -> work -> review -> compound`) and adds a parallel research track. Each piece is independently useful, but the workflow command orchestrates the sequence. The agent integration means research automatically compounds into every feature decision. + +**Rejected alternatives:** +- Standalone skills (no orchestration, less "compound" feeling) +- Single monolithic skill (doesn't follow plugin's pattern of specialized, focused tools) + +## New Components (5 total) + +### 1. Workflow Command: `/workflows:research` + +Orchestrates the full research loop as a single command with phases (matching how `/workflows:brainstorm` and `/workflows:plan` work — one command file, multiple phases, skills provide process knowledge): + +- **Phase 1: Plan** — Create a research plan (loads `research-plan` skill) +- **Phase 2: Process** — Process a transcript into structured insights (loads `transcript-insights` skill) +- **Phase 3: Personas** — Build/update persona documents from accumulated insights (loads `persona-builder` skill) + +The command accepts an optional argument to jump to a specific phase (e.g., `/workflows:research process`). Without an argument, it asks which phase to run. Each phase is independent — users can run them in any order as their research progresses. + +### 2. Skill: `research-plan` + +Creates a structured research plan document in `docs/research/plans/`. Grounded in Continuous Discovery Habits — plans are **outcome-focused** (tied to a metric, not a feature) and generate **story-based discussion guides** following the Mom Test. + +**Outputs:** +```yaml +--- +title: Dashboard Usability Study +date: 2026-02-10 +status: planned +outcome: "Reduce time-to-insight for dashboard users by 30%" +hypotheses: + - Users check dashboards first thing in the morning for problems + - Users need exportable reports for stakeholders +participant_criteria: + - Marketing managers at B2B SaaS companies + - Active dashboard users (3+ times/week) +sample_size: 5 +screener_questions: + - "How often do you use a data dashboard in your work?" + - "When was the last time you shared data with a colleague or stakeholder?" +--- + +## Research Objectives +1. Understand daily dashboard usage patterns +2. Identify export/reporting pain points + +## Three Most Important Things to Learn +1. What triggers a dashboard visit and what do users look for first? +2. How do users currently share data with stakeholders? +3. What workarounds exist for unmet dashboard needs? + +## Discussion Guide + +### Warm-up (2-3 min) +- Tell me about your role and how data fits into your day-to-day + +### Story Collection (15-20 min) +*Story-based prompts — ask about specific past behavior, not opinions:* +- "Tell me about the last time you opened your dashboard. What was happening? What were you looking for?" +- "Tell me about a recent time you needed to share data with someone. Walk me through what happened." + +**Follow-up probes:** +- "What happened next?" +- "How did you feel at that point?" +- "What did you end up doing?" + +*Redirect generalizations:* If participant says "I usually..." → "Can you think of a specific time that happened? Walk me through it." + +### Wrap-up (2-3 min) +- "Is there anything else I should have asked?" +- "Who else should I talk to about this?" + +## Post-Interview Checklist +- [ ] Complete interview snapshot within 15 minutes +- [ ] Run `/workflows:research process` on transcript +- [ ] Note any follow-up items or new hypotheses +``` + +**Key features:** +- **Outcome-focused** — plans start with a measurable outcome, not a feature idea +- Generates **story-based discussion guides** (Teresa Torres) — "Tell me about the last time..." not "Would you use...?" +- Embeds **Mom Test principles** — past behavior, no pitching, redirect generalizations +- Includes **screener questions** for participant recruitment +- Includes **"Three Most Important Things to Learn"** pre-interview focus (Mom Test) +- Includes **post-interview checklist** to close the loop with transcript processing +- Links back to features/brainstorms that motivated the research + +### 3. Skill: `transcript-insights` + +Takes raw interview transcripts (from `docs/research/transcripts/`) and produces two outputs: a structured **interview snapshot** (Teresa Torres) and **atomic research nuggets** for cross-interview analysis. + +**Process:** The skill follows the highlight → tag → synthesize flow from the discovery playbook. It reads the raw transcript, identifies key moments, tags them, and produces structured output. + +**Input:** Raw transcript `.md` file path (from `docs/research/transcripts/`) or pasted text + +**Output:** `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` +```yaml +--- +participant_id: user-001 +participant_role: Marketing Manager, B2B SaaS +date: 2026-02-10 +research_plan: dashboard-usability-study +focus: Dashboard usage patterns +duration_minutes: 30 +tags: [dashboard, export, morning-workflow, b2b-saas] +--- + +## Interview Snapshot + +**Participant:** Marketing Manager at mid-size B2B SaaS (3 years in role) +**Memorable Quote:** "First thing every morning, I check for red flags." + +### Experience Map +1. Arrives at work, opens dashboard before email +2. Scrolls past positive metrics looking for problems +3. Finds an anomaly, tries to export for stakeholder +4. Export is buried — takes 3 attempts to find button +5. Gives up, screenshots instead + +### Opportunities (needs, pain points, desires) +- Needs to surface problems quickly without scanning everything +- Needs to export data in static formats (PDF) for stakeholders +- Wants dashboard to proactively alert on anomalies + +### Follow-up Items +- How do other roles (engineers, executives) use the same dashboard? +- What does "red flag" mean specifically — thresholds? Trends? + +## Atomic Insights + +### Insight: Morning dashboard ritual +**Quote:** "First thing every morning, I check for red flags." +**Implication:** Dashboard needs to surface problems quickly, not show everything. +**Tags:** [information-hierarchy, morning-workflow, pain-point] + +### Insight: Export friction +**Quote:** "My boss wants a PDF, not a link." +**Implication:** Export to static formats is a core need, not a nice-to-have. +**Tags:** [reporting, export, workaround] + +### Insight: Screenshot workaround +**Observation:** Participant gave up on export after 3 attempts and used screenshots instead. +**Implication:** Workaround signals unmet need — export flow is broken, not just inconvenient. +**Tags:** [workaround, export, abandonment] + +## Behavioral Observations +- Opened dashboard before email +- Scrolled past charts to find the "alerts" section +- Attempted export 3 times before finding the button +- Fell back to screenshots when export failed + +## Hypotheses Supported/Challenged +- [SUPPORTED] Users check dashboards first thing in the morning +- [NEW] Users prioritize problems over positive metrics +- [NEW] Export is broken enough that users have workarounds +``` + +**Key features:** +- Produces **interview snapshots** (Teresa Torres) — one-page summaries with experience maps, not just raw notes +- Extracts **atomic research nuggets** — smallest reusable units of insight with tags for cross-interview search +- Uses a **tag taxonomy** (behavioral, emotional, need/pain point, descriptive) consistent across all interviews +- **Experience maps** — timeline of the participant's story showing key moments +- Identifies **opportunities** (needs, pain points, desires) — the language of the Opportunity Solution Tree +- Captures **workarounds** explicitly — strongest signal of unmet needs +- Links back to research plan and tracks hypothesis validation + +### 4. Skill: `persona-builder` + +Synthesizes insights across multiple interviews into living persona documents. + +**Output:** `docs/research/personas/persona-name.md` +```yaml +--- +name: The Data-Driven Manager +role: Marketing Manager +company_type: B2B SaaS +last_updated: 2026-02-10 +interview_count: 3 +confidence: medium +--- + +## Goals +1. Prove marketing ROI to leadership +2. Identify underperforming campaigns before they waste budget + +## Frustrations +1. Too much data, hard to find what matters +2. Exporting for reports is tedious — "My boss wants a PDF, not a link" +3. Dashboard doesn't surface problems proactively + +## Behaviors +- Checks dashboard first thing every morning (3/3 participants) +- Scrolls past positive metrics to find problems (2/3 participants) +- Exports data weekly for stakeholder reports (3/3 participants) + +## Quotes +- "First thing every morning, I check for red flags." +- "I need to see problems, not everything." +- "My boss wants a PDF, not a link." + +## Opportunities (for Opportunity Solution Tree) +| Opportunity | Evidence Strength | Source Interviews | +|-------------|------------------|-------------------| +| Users need to surface problems without scanning everything | Strong (3/3) | user-001, user-003, user-005 | +| Users need to export data in static formats for stakeholders | Strong (3/3) | user-001, user-003, user-005 | +| Users want proactive alerts instead of manual checking | Medium (2/3) | user-001, user-005 | + +## Evidence +- Based on interviews: user-001, user-003, user-005 +- Research plan: dashboard-usability-study +``` + +**Key features:** +- Synthesizes across multiple interviews (not just one) +- Tracks confidence level based on participant count +- Includes an **Opportunities table** using OST language (opportunities, not solutions — feeds directly into Opportunity Solution Trees) +- Links back to source interviews for traceability +- Updates incrementally as new interviews are processed + +### 5. Agent: `user-research-analyst` + +A research agent (parallel to `learnings-researcher`) that surfaces relevant personas and insights during brainstorming and planning. + +**Invoked by:** `/workflows:brainstorm` (Phase 1) and `/workflows:plan` (Step 1) + +**What it does:** +- Searches `docs/research/personas/` for personas relevant to the feature being planned +- Searches `docs/research/interviews/` for insights matching the feature area +- Returns a summary: relevant personas, key quotes, confidence levels, feature implications + +**Integration points:** +- `/workflows:brainstorm` Phase 1.1 — surfaces personas alongside repo research +- `/workflows:plan` Step 1 — runs in parallel with `learnings-researcher` and `repo-research-analyst` + +## Directory Structure + +``` +docs/research/ +├── plans/ # Research plans (discussion guides, hypotheses, outcomes) +│ └── dashboard-usability-study.md +├── transcripts/ # Raw interview transcripts as markdown +│ ├── 2026-02-10-user-001-transcript.md +│ ├── 2026-02-10-user-002-transcript.md +│ └── ... +├── interviews/ # Processed interview snapshots + atomic insights +│ ├── 2026-02-10-user-001.md +│ ├── 2026-02-10-user-002.md +│ └── ... +└── personas/ # Synthesized persona documents + ├── data-driven-manager.md + └── ... +``` + +**Transcripts are markdown files.** Users paste or save their raw interview transcripts as `.md` files in `transcripts/`. The `transcript-insights` skill reads from here and writes structured output to `interviews/`. Raw transcripts are kept as source-of-truth — the processed insights are derived artifacts that can be regenerated. + +## How Research Compounds + +``` +/workflows:research (Plan) → docs/research/plans/ + ↓ + (conduct interviews externally) + ↓ + (save transcript to docs/research/transcripts/) + ↓ +/workflows:research (Process) → docs/research/interviews/ + ↓ +/workflows:research (Personas) → docs/research/personas/ + +--- PR 1 boundary (above) --- +--- PR 2 boundary (below) --- + +/workflows:brainstorm ← user-research-analyst auto-surfaces personas +/workflows:plan ← user-research-analyst auto-surfaces insights + ↓ + (build feature, ship, observe) + ↓ +/workflows:research (Plan) → new research to validate +``` + +## Key Decisions + +1. **Workflow command with phases** — `/workflows:research` is one command with three phases (Plan, Process, Personas), matching how other workflow commands work +2. **Three modular skills** — each phase is a standalone skill the workflow orchestrates +3. **YAML frontmatter on everything** — follows the `docs/solutions/` pattern so AI agents can filter by metadata +4. **Raw transcripts stored as markdown** — `docs/research/transcripts/` holds raw `.md` transcripts; `interviews/` holds processed insights derived from them +5. **Living personas** — personas update incrementally as new interviews are processed, with confidence tracking +6. **Methodology baked in** — skills embed Teresa Torres (story-based interviewing, interview snapshots, OST) and Mom Test (past behavior, no pitching) principles directly into their output templates +7. **`docs/research/` directory** — follows existing `docs/solutions/`, `docs/brainstorms/`, `docs/plans/` pattern +8. **Two-PR delivery** — PR 1: research workflow, skills, agent, and directory structure. PR 2: modify `/workflows:brainstorm` and `/workflows:plan` to auto-call `user-research-analyst`. Keeps PRs focused and independently shippable. +9. **Discovery playbook as reference** — the discovery playbook is bundled as `references/discovery-playbook.md` in the skills, giving AI access to the full methodology + +## Open Questions + +1. **Experiment design (stretch goal):** Should `/workflows:research experiment` be a fourth phase that generates hypotheses and suggests validation approaches (A/B tests, usage metrics to watch)? +2. **Cross-interview theming:** Should `persona-builder` also generate a `docs/research/themes.md` that tracks cross-cutting themes and their evidence strength? +3. **Transcript input:** Should `transcript-insights` accept only pasted text and file paths (simplest), or also handle URLs to transcript services? Start with text/file, extend later if needed. + +## Reference Materials + +The following will be bundled as `references/` in the skills: + +- **`discovery-playbook.md`** — Continuous Product Discovery Playbook (Teresa Torres + Mom Test methodology, interview structure, snapshot format, tagging taxonomy, Opportunity Solution Trees) +- Source: `/Users/matthewthompson/Downloads/discovery-playbook.md` + +Key concepts incorporated from the playbook: +- **Outcome-focused research plans** — tied to metrics, not features (Section 2.1) +- **Story-based interviewing** — "Tell me about the last time..." not "Would you use...?" (Section 3.3) +- **Mom Test principles** — past behavior, no pitching, redirect generalizations (Section 3.2) +- **Interview snapshots** — one-page synthesis with experience maps, done within 15 min (Section 4.2) +- **Atomic research nuggets** — smallest reusable insight units with tags (Section 5.5) +- **Highlight → Tag → Theme flow** — structured analysis progression (Sections 5.2-5.4) +- **Opportunity language** — needs, pain points, desires (not features) for OST compatibility (Section 6.1) + +## Stretch Goals (Future) + +- `/workflows:research experiment` — design experiments to validate hypotheses, suggest A/B tests and metrics to watch (OST "Experiments" layer) +- `/workflows:research validate` — compare feature usage data against research predictions +- Cross-interview theme tracking with `docs/research/themes.md` and confidence aggregation +- Integration with analytics MCP servers for automated pattern detection (per Every guide's "more coming soon") +- Opportunity Solution Tree visualization — structured view connecting outcomes → opportunities → solutions → experiments diff --git a/docs/brainstorms/2026-02-13-user-research-workflow-integration-brainstorm.md b/docs/brainstorms/2026-02-13-user-research-workflow-integration-brainstorm.md new file mode 100644 index 00000000..4981d560 --- /dev/null +++ b/docs/brainstorms/2026-02-13-user-research-workflow-integration-brainstorm.md @@ -0,0 +1,184 @@ +--- +date: 2026-02-13 +topic: user-research-workflow-integration +--- + +# User Research Integration into Brainstorm & Plan Workflows + +## What We're Building + +Wire user research artifacts (personas, interview insights, opportunities) into the brainstorm and plan workflows so that product decisions are grounded in user evidence rather than assumptions. + +Today, `/workflows:research` produces structured artifacts in `docs/research/` (personas, interview snapshots, research plans) and the `user-research-analyst` agent knows how to search them — but nothing in brainstorm or plan actually calls it. The research workflow hands off to brainstorm, but brainstorm doesn't consume the output. This integration closes that gap. + +## Why This Approach + +We considered three scoping strategies: + +1. **All at once** — wire basics + deeper integrations + plan + work in a single pass. Rejected: too broad, hard to validate incrementally. +2. **Brainstorm-only** — focus exclusively on brainstorm, defer plan. Rejected: the plan wiring is trivial and documented as a TODO already. +3. **Phased approach** (chosen) — Phase 1 wires the basics into both brainstorm and plan. Phase 2 layers in deeper brainstorm integrations. This lets us ship value quickly and validate each layer before adding the next. + +## Key Decisions + +- **Phased delivery**: Phase 1 (basic wiring) then Phase 2 (deeper brainstorm integrations) +- **Brainstorm + Plan first**: These are where research evidence has the highest leverage. Work workflow integration deferred. +- **Parallel execution**: `user-research-analyst` runs in parallel with existing agents — no serial bottleneck added +- **Graceful degradation**: When `docs/research/` is empty, the agent returns a note suggesting `/workflows:research` — no errors, no blocking + +## Phase 1: Basic Wiring + +### 1a. Wire `user-research-analyst` into Brainstorm Phase 1.1 + +**Current state:** Brainstorm Phase 1.1 runs only `repo-research-analyst`. + +**Change:** Add `user-research-analyst` as a parallel agent in Phase 1.1. The brainstorm would run: + +``` +- Task repo-research-analyst("Understand existing patterns related to: ") +- Task user-research-analyst("Surface research relevant to: ") +``` + +**What this unlocks:** Before the collaborative dialogue begins, the brainstormer knows which personas are relevant, what opportunities exist, and what pain points users have expressed. The "understand the idea" conversation becomes evidence-informed. + +**Output flow:** Present a brief summary of relevant research findings (personas, key insights, research gaps) before starting the collaborative dialogue in Phase 1.2. Even without the deeper Phase 2 integrations, this gives the user and the brainstorm process shared context from real user evidence. + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/brainstorm.md` — Phase 1.1 +- `plugins/compound-engineering/agents/research/user-research-analyst.md` — remove "to be wired in PR 2" note + +### 1b. Wire `user-research-analyst` into Plan Step 1 + +**Current state:** Plan Step 1 runs `repo-research-analyst` + `learnings-researcher` in parallel. + +**Change:** Add `user-research-analyst` as a third parallel agent: + +``` +- Task repo-research-analyst(feature_description) +- Task learnings-researcher(feature_description) +- Task user-research-analyst(feature_description) +``` + +**Step 1.6 (Consolidate Research) update:** Add "User Research Findings" as a consolidation category alongside repo patterns and institutional learnings. Structure: + +- Relevant personas and their relationship to this feature +- Key insights and quotes from interviews +- Research gaps (areas where coverage is thin) + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/plan.md` — Step 1 and Step 1.6 +- `plugins/compound-engineering/agents/research/user-research-analyst.md` — remove "to be wired in PR 2" note + +## Phase 2: Deeper Brainstorm Integrations + +### 2a. Opportunity-Driven Brainstorm Initiation + +**When:** Brainstorm starts with no feature description or a vague one. + +**Behavior:** Check persona opportunity tables for unaddressed opportunities. Present them as starting points: + +> "Your research has identified these opportunities: +> 1. [Persona X] needs faster data export (high frequency, low satisfaction) +> 2. [Persona Y] struggles with team collaboration features +> 3. [Persona Z] wants better mobile support +> +> Would you like to explore one of these, or describe something else?" + +This flips brainstorming from "what should we build?" to "your users told you what they need." + +**Dependency:** Requires persona opportunity tables to be populated — the `persona-builder` skill must have run at least once via `/workflows:research personas`. When no personas exist, this step is skipped gracefully (same as Phase 1 graceful degradation). + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/brainstorm.md` — new Phase 0.5 between assessment and Phase 1 +- May need a lightweight "opportunity scanner" helper or extend `user-research-analyst` output + +### 2b. Research-Informed Question Generation + +**When:** After `user-research-analyst` surfaces findings in Phase 1.1, entering Phase 1.2 (Collaborative Dialogue). + +**Behavior:** Use research findings to shape questions. Instead of generic questions: + +- Generic: "Who are the users of this feature?" +- Research-informed: "Your research shows two user types here — [Persona A] who uses this daily vs [Persona B] who uses it quarterly. Should we optimize for one or both?" + +- Generic: "What problem does this solve?" +- Research-informed: "Interviews show users currently work around this by [workaround]. Should we replace that workaround entirely, or build alongside it?" + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/brainstorm.md` — Phase 1.2 guidelines +- `plugins/compound-engineering/skills/brainstorming/SKILL.md` — add "research-informed questioning" technique + +### 2c. Persona-Grounded Approach Evaluation + +**When:** Phase 2 (Explore Approaches), evaluating 2-3 approaches. + +**Behavior:** Evaluate each approach against relevant personas: + +> **Approach A: Simple Export Button** +> - Serves [Persona X] well (matches their "quick export" workflow from interviews) +> - Doesn't address [Persona Y]'s need for scheduled exports +> +> **Approach B: Export Configuration Panel** +> - Addresses both [Persona X] and [Persona Y] +> - Higher complexity; [Persona X] may find it slower than current workaround + +This makes trade-off discussions concrete and user-grounded instead of hypothetical. + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/brainstorm.md` — Phase 2 guidelines +- `plugins/compound-engineering/skills/brainstorming/SKILL.md` — add persona-grounded evaluation pattern + +### 2d. Research Evidence in Brainstorm Capture + +**When:** Phase 3 (Capture the Design), writing the brainstorm document. + +**Behavior:** Add a "Research Evidence" section to the brainstorm document template: + +```markdown +## Research Evidence + +### Relevant Personas +- **[Persona Name]** (confidence: high) — [one-line relevance] + +### Key Quotes +- "[quote]" — participant NNN, on [topic] + +### Opportunities Addressed +- [Opportunity from persona table] → addressed by [decision] + +### Research Gaps +- [Areas where we're making assumptions without research backing] +``` + +This creates a traceable chain: research → brainstorm decisions → plan → implementation. + +**Files to modify:** +- `plugins/compound-engineering/commands/workflows/brainstorm.md` — Phase 3 template +- `plugins/compound-engineering/skills/brainstorming/SKILL.md` — update design doc structure + +## Open Questions + +- **`deepen-plan` coverage: resolved.** `deepen-plan` explicitly runs ALL agents from ALL sources with no relevance filtering (Step 5 rule: "Do NOT filter agents by relevance - run them ALL"). So `user-research-analyst` will be picked up automatically — no changes needed there. +- **Opportunity tracking:** Should we track which opportunities have been addressed across brainstorms? This was deferred (Tier 5) but could be lightweight metadata in the brainstorm YAML frontmatter. +- **Research freshness:** Should we warn when persona data is stale (>90 days)? Deferred but low-effort to add. + +## Deferred Ideas (Future Phases) + +These were explored but deferred based on priority: + +| Idea | Tier | Reason Deferred | +|------|------|----------------| +| Persona-informed stakeholder analysis in plan | 3 | Plan wiring covers the basics; deeper integration later | +| Research-backed acceptance criteria in plan | 3 | Valuable but complex; needs careful design | +| Research gap detection warnings | 3 | Nice-to-have; basic wiring surfaces gaps naturally | +| Persona context during work setup | 4 | Light touch; work executes plans that already have context | +| Persona-driven test scenarios | 4 | Interesting but speculative; validate Phase 1-2 first | +| Research-to-brainstorm handoff with context | 5 | Can be addressed when improving research workflow | +| Brainstorm-to-research feedback loop | 5 | Closes the loop; depends on Phase 2 working well | +| Opportunity tracking across workflows | 5 | Needs Phase 2a working first | +| Research freshness indicators | 5 | Low-effort but low-priority | + +## Next Steps + +→ `/workflows:plan` for Phase 1 implementation (basic wiring into brainstorm + plan) +→ Validate Phase 1 works with real research data before starting Phase 2 diff --git a/docs/plans/2026-02-11-feat-user-research-workflow-plan.md b/docs/plans/2026-02-11-feat-user-research-workflow-plan.md new file mode 100644 index 00000000..505f4fcd --- /dev/null +++ b/docs/plans/2026-02-11-feat-user-research-workflow-plan.md @@ -0,0 +1,643 @@ +--- +title: "feat: Add user research workflow" +type: feat +date: 2026-02-11 +source_brainstorm: docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md +--- + +# feat: Add User Research Workflow + +## Enhancement Summary + +**Deepened on:** 2026-02-11 +**Sections enhanced:** 7 +**Research agents used:** create-agent-skills evaluator, brainstorming skill evaluator, best-practices-researcher, architecture-strategist, code-simplicity-reviewer, pattern-recognition-specialist, persona-merge-logic analyst + +### Key Improvements +1. Added exact skill description strings and agent `` blocks (no longer deferred to implementation) +2. Added field-by-field persona merge specification with contradiction handling and Divergences section +3. Fixed blocking frontmatter gap: interview snapshots now output separate `role`, `company_type`, and `source_transcript` fields +4. Simplified Phase 0 to lightweight menu (not a full phase), reduced handoff from 5 to 3 options +5. Added Human Review Checklist requirement to all AI-generated research output +6. Resolved agent `model` field: use `inherit` (not `haiku`) per v2.23.1 policy +7. Added exact CHANGELOG entry text and pre-existing metadata drift fix + +### New Considerations Discovered +- AI-generated quotes must be verified against source transcripts (highest-risk failure mode) +- Persona contradictions are normal in qualitative research -- need a Divergences section, not silent count updates +- Pre-existing README count drift (says 25 commands/16 skills, actually 24/18) and marketplace.json version drift (2.31.0 vs plugin.json 2.31.1) must be fixed in Phase 4 + +--- + +## Overview + +Add a user research workflow to the compound-engineering plugin that makes user research a first-class input to AI-assisted development. Today, the plugin has zero research capabilities -- insights from user interviews sit in Google Docs and never reach the developer. This workflow closes that gap by providing tools to plan research, process transcripts into structured insights, and synthesize personas. + +**Scope:** PR 1 only. Creates the research workflow, three skills, one agent, and directory structure. PR 2 (integration with `/workflows:brainstorm` and `/workflows:plan` to auto-surface research) is deferred to a follow-up. + +**Methodology:** Teresa Torres' *Continuous Discovery Habits* (story-based interviewing, interview snapshots, Opportunity Solution Trees) and Rob Fitzpatrick's *The Mom Test* (past behavior over future speculation). A discovery playbook reference document is bundled with each skill. + +## Problem Statement + +The compound engineering plugin follows the workflow: brainstorm -> plan -> work -> review -> compound. But there is no research step. User insights from interviews, customer calls, and usability tests are disconnected from the development workflow. This means: + +- Feature decisions are made without grounding in user evidence +- Research artifacts (transcripts, notes) rot in Google Docs +- Personas don't exist or are static documents that never update +- The "compounding" philosophy breaks down at the research-to-development boundary + +## Proposed Solution + +Add a parallel research track that mirrors existing workflow patterns: + +``` +/workflows:research (Plan) -> docs/research/plans/ + | + (conduct interviews externally) + | + (save transcript to docs/research/transcripts/) + | +/workflows:research (Process) -> docs/research/interviews/ + | +/workflows:research (Personas) -> docs/research/personas/ +``` + +**Five new components:** +1. `/workflows:research` command -- orchestrates the research loop with 3 phases +2. `research-plan` skill -- creates structured research plans +3. `transcript-insights` skill -- processes transcripts into interview snapshots +4. `persona-builder` skill -- synthesizes personas from interviews +5. `user-research-analyst` agent -- searches research artifacts (created but not wired into other workflows until PR 2) + +**One reference file copied into each skill:** +- `references/discovery-playbook.md` -- Continuous Product Discovery Playbook (source: `~/Downloads/discovery-playbook.md`) + +## Technical Approach + +### Architecture + +All components follow established plugin patterns exactly: + +- **Workflow command**: Phase-based structure with `#$ARGUMENTS`, AskUserQuestion at decision points, skill loading via `"Load the X skill"` directive. Matches `workflows:brainstorm.md`. +- **Skills**: YAML frontmatter (`name`, `description`), reference file linking via `[file.md](./references/file.md)`, imperative voice. Matches `brainstorming/SKILL.md`. +- **Agent**: YAML frontmatter (`name`, `description`, `model: inherit`), `` block, grep-first search strategy, structured output format. Matches `learnings-researcher.md`. + +### Research Insights: Architecture + +**Agent model field:** Use `model: inherit` (not `haiku`). The CHANGELOG v2.23.1 established that all agents use `model: inherit` so they match the user's configured model. Only `lint` keeps `model: haiku`. The `learnings-researcher` still shows `model: haiku` in its file but this is stale -- follow the policy, not the stale file. ([Source: pattern-recognition-specialist, architecture-strategist]) + +**Discovery playbook duplication (3 copies):** This follows established convention -- every existing skill with references has them in its own `references/` directory. No skill shares references with another. The 3x duplication of the 415-line playbook is a maintenance cost but the convention is correct. All three copies must be byte-identical. Phase 5 verification should include a checksum comparison. ([Source: architecture-strategist, code-simplicity-reviewer]) + +**Skill frontmatter considerations:** Each skill should specify `allowed-tools` in frontmatter (Read, Write, Bash, Grep) to reduce user permission prompts. Consider `disable-model-invocation: true` since these skills write files (side effects). ([Source: create-agent-skills evaluator]) + +**File path contracts:** Document these at the top of the workflow command so the coupling between command and skill output conventions is visible and maintainable: +- Plans: `docs/research/plans/YYYY-MM-DD--research-plan.md` +- Transcripts: `docs/research/transcripts/*.md` (user-provided) +- Interviews: `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` +- Personas: `docs/research/personas/.md` + +([Source: brainstorming evaluator]) + +**Directory structure created silently at command start (not a "phase"):** +``` +docs/research/ + plans/ # Research plans with discussion guides + transcripts/ # Raw interview transcripts (user-provided .md files) + interviews/ # Processed interview snapshots (generated) + personas/ # Synthesized persona documents (generated) +``` + +### Standardized Terminology + +Use these terms consistently across all components: +- **Research plan** (not "plan document" or "discussion guide document") +- **Interview snapshot** (not "processed interview" or "interview file") +- **Persona** (not "persona document" or "persona file") +- **Transcript** (not "raw transcript" or "transcript file") + +([Source: create-agent-skills evaluator]) + +### Implementation Phases + +#### Phase 1: Reference File and Skills (3 skills + 1 reference) + +Create the three skills and their shared reference file. These are the core knowledge components. + +**Tasks:** + +- [x] Copy `~/Downloads/discovery-playbook.md` to three locations: + - `plugins/compound-engineering/skills/research-plan/references/discovery-playbook.md` + - `plugins/compound-engineering/skills/transcript-insights/references/discovery-playbook.md` + - `plugins/compound-engineering/skills/persona-builder/references/discovery-playbook.md` + +- [x] Create `plugins/compound-engineering/skills/research-plan/SKILL.md` + - Frontmatter: + ```yaml + name: research-plan + description: "Create structured research plans with outcome-focused objectives, discussion guides, and screener questions. Use when planning user interviews, customer research, or discovery work." + ``` + - **Note: The current year is 2026.** (Include year note in skill body) + - Target length: ~200 lines + - Structure: Quick Start section, step-by-step Instructions, Output Template, Examples section + - Guides creating research plan at `docs/research/plans/YYYY-MM-DD--research-plan.md` + - Content: outcome-focused objectives, story-based discussion guide template, Mom Test principles, participant criteria, screener questions, post-interview checklist, "Three Most Important Things to Learn" section + - Output template with YAML frontmatter: `title`, `date`, `status: planned`, `outcome`, `hypotheses`, `participant_criteria`, `sample_size`, `screener_questions`, `interviews_completed: 0` + - References discovery playbook via `[discovery-playbook.md](./references/discovery-playbook.md)` + - Include `## Human Review Checklist` in the output template + +- [x] Create `plugins/compound-engineering/skills/transcript-insights/SKILL.md` + - Frontmatter: + ```yaml + name: transcript-insights + description: "Process interview transcripts into structured snapshots with tagged insights, experience maps, and opportunity identification. Use when a transcript exists in docs/research/transcripts/ or when pasting interview content." + ``` + - **Note: The current year is 2026.** + - Target length: ~300 lines + - Structure: Quick Start, Instructions, Tag Taxonomy, Output Template, Examples + - Accepts file path from `docs/research/transcripts/` OR pasted text as input. Use `$ARGUMENTS` for file path; prompt if empty. + - Asks which research plan the transcript belongs to (list plans by title from frontmatter, most recent first, cap at 5-7 plus "Ad-hoc / no plan"). Handle "no plan" as ad-hoc. + - Generates interview snapshot at `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` + - Output includes: interview snapshot (Teresa Torres one-page format), experience map (timeline), atomic insights with two-tier tags, opportunities in OST language, hypothesis tracking (SUPPORTED/MIXED/CHALLENGED/NEW), behavioral observations + - **Interview frontmatter must output separate fields** (not a composite string): + ```yaml + participant_id: user-001 + role: Marketing Manager # Separate field (not composite) + company_type: B2B SaaS # Separate field (not composite) + date: 2026-02-10 + research_plan: dashboard-usability-study + source_transcript: 2026-02-10-user-001-transcript.md # Links back to source + focus: Dashboard usage patterns + duration_minutes: 30 + tags: [dashboard, export, morning-workflow] + ``` + - Tag taxonomy defined in skill: + - **Type tags (fixed set, exactly ONE per insight):** pain-point, need, desire, behavior, workaround, motivation + - **Topic tags (semi-open, 1-3 per insight):** lowercase, hyphenated, singular. Check existing interviews for existing tags before creating new ones. + - References discovery playbook via `[discovery-playbook.md](./references/discovery-playbook.md)` + - Include `## Human Review Checklist` in output: + ``` + - [ ] All quotes verified against source transcript + - [ ] Experience map accurately reflects story arc + - [ ] Opportunities reflect participant needs, not assumed solutions + - [ ] Tags accurate and consistent with existing taxonomy + - [ ] No insights fabricated or composited from multiple participants + ``` + +- [x] Create `plugins/compound-engineering/skills/persona-builder/SKILL.md` + - Frontmatter: + ```yaml + name: persona-builder + description: "Synthesize personas from processed interview snapshots with confidence tracking and evidence-backed opportunities. Use when processed interviews exist in docs/research/interviews/ or when building or updating personas." + ``` + - **Note: The current year is 2026.** + - Target length: ~250 lines + - Structure: Quick Start, Instructions (Create New / Merge Existing), Merge Specification, Output Template, Examples + - Reads processed interviews from `docs/research/interviews/` + - **Persona matching and merge flow** (see Persona Merge Specification below) + - Generates persona at `docs/research/personas/.md` + - Output includes: goals, frustrations, behaviors (with participant counts), opportunities table with evidence strength, quotes (cap at 5-7), Divergences section (when contradictions exist), source interview links + - Output YAML frontmatter: + ```yaml + name: The Data-Driven Manager + role: Marketing Manager + company_type: B2B SaaS + last_updated: 2026-02-10 + interview_count: 3 + confidence: medium + source_interviews: [user-001, user-003, user-005] + version: 1 + ``` + - Confidence thresholds: 1 = low, 2-3 = medium, 4+ = high + - References discovery playbook via `[discovery-playbook.md](./references/discovery-playbook.md)` + - Include `## Human Review Checklist` in output + +### Research Insights: Persona Merge Specification + +This is the highest-complexity logic in the plan. The following rules govern how persona-builder handles merging new interview data into existing personas. + +**Matching algorithm:** +1. Extract `role` and `company_type` from the new interview's frontmatter +2. Scan existing personas in `docs/research/personas/` for matches on both fields +3. **Exact match** on both fields: present as merge candidate with context (persona name, interview count, confidence, key characteristics) +4. **Partial match** (role matches, company_type differs or vice versa): present as possible candidate with differences highlighted +5. **No match**: offer to create new persona (ask user for persona name) +6. **Multiple matches**: present numbered list of candidates with differentiators, plus "Create new" option +7. User always confirms the choice via AskUserQuestion + +**Confirmation prompt must show:** existing persona name, current interview count, confidence level, 2-3 key characteristics. Show the new interview's role and focus for comparison. + +**Field-by-field update rules when merging:** + +| Field Category | Update Strategy | +|---------------|----------------| +| Frontmatter metadata (`last_updated`, `interview_count`, `confidence`, `version`, `source_interviews`) | Always auto-update. Increment version, append participant_id to source_interviews, recalculate confidence. | +| Persona name and role | Preserve unless user explicitly requests change. | +| Goals | Append new goals not already listed. Flag potential duplicates with `[Review: possible overlap with Goal #N]`. | +| Frustrations | Append new frustrations. Flag potential duplicates. | +| Behaviors | Update participant counts as `(N/M participants)` where M = total interview count. When a behavior is not mentioned, do NOT change the count (absence is not evidence). Add new behaviors. | +| Quotes | Add the single most representative new quote. Keep total at 5-7 max. Note "Additional quotes in source interviews." | +| Opportunities table | Add new rows. Update evidence strength counts for existing rows only when the new interview explicitly addresses that opportunity. | +| Evidence section | Always append new participant_id and research plan. | + +**Contradiction handling:** +When a new interview contradicts an existing finding, do NOT silently update counts. Instead: +1. Keep both data points with their evidence counts +2. Add to a `## Divergences` section in the persona: + ``` + | Finding | Majority View | Minority View | Split | + |---------|--------------|---------------|-------| + | Morning dashboard check | Check first thing (3/4) | Check after standup (1/4) | 3:1 | + ``` +3. When divergences reach 40/60 split or closer, flag for potential persona segmentation +4. Surface contradictions in the merge confirmation prompt + +**Evidence strength thresholds:** +- Weak: less than 33% of participants, or only 1 interview +- Medium: 33-66% of participants +- Strong: 67%+ of participants + +**Hypothesis status transitions:** +- SUPPORTED: 75%+ of evidence supports +- MIXED: 40-75% support +- CHALLENGED: less than 40% support +- NEW: emerged from this interview, no prior evidence + +([Source: persona-merge-logic analyst, best-practices-researcher, architecture-strategist]) + +**Success criteria:** +- Each skill's `name` matches its directory name +- All `references/` files linked with `[filename.md](./references/filename.md)` syntax (no bare backticks) +- Descriptions follow "Does X. Use when Y." pattern +- Imperative voice throughout (no "you should") +- Interview frontmatter outputs separate `role`, `company_type`, and `source_transcript` fields + +#### Phase 2: Workflow Command + +Create the orchestrating command that ties the skills together. + +**Tasks:** + +- [x] Create `plugins/compound-engineering/commands/workflows/research.md` + - Frontmatter: `name: workflows:research`, `description: Plan user research, process interview transcripts, and build personas from accumulated insights`, `argument-hint: "[plan|process|personas]"` + - Year note: "The current year is 2026." + - **File path contracts** documented at top of command (plans, transcripts, interviews, personas paths) + - Argument injection: ` #$ARGUMENTS ` + - If argument is empty, run phase selection. If argument matches a phase name, jump directly to that phase. If argument is unrecognized, show phase menu with note about valid arguments. + + **Directory setup (silent, always runs before any phase):** + - Create `docs/research/` directories with `mkdir -p` if they don't exist. This is boilerplate, not a named phase. + + **Phase selection (when no argument given):** + - Brief artifact status (2-3 lines max): "N plans, N transcripts (M unprocessed), N interviews, N personas" + - Unprocessed transcript detection: grep interview frontmatter for `source_transcript` field matching each transcript filename. Simpler fallback: count files in `transcripts/` minus files in `interviews/`. + - AskUserQuestion with three options: Plan, Process, Personas. Lead with recommendation based on state (e.g., unprocessed transcripts exist -> recommend Process). + + **Phase 1: Plan** + - Load the `research-plan` skill + - Skill handles all research plan creation logic + - **Return contract:** Skill creates a file at `docs/research/plans/YYYY-MM-DD--research-plan.md` + + **Phase 2: Process** + - Check for transcripts in `docs/research/transcripts/` + - If no transcripts: "No transcripts found in `docs/research/transcripts/`. Save your interview transcript as a `.md` file there, then re-run this phase." (Transcript format guidance belongs in the skill, not here.) + - If exactly one unprocessed transcript: confirm with user before proceeding + - If multiple unprocessed transcripts: list them, ask user to select via AskUserQuestion + - Load the `transcript-insights` skill with selected transcript + - **Return contract:** Skill creates a file at `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` + + **Phase 3: Personas** + - Check for processed interviews in `docs/research/interviews/` + - If no interviews: guide user to process transcripts first + - Load the `persona-builder` skill + - **Return contract:** Skill creates or updates a file at `docs/research/personas/.md` + + **Handoff (after any phase completes):** + - Announce the created/updated file path + - Use AskUserQuestion with three options: + 1. "Continue research" -- routes back to phase selection menu + 2. "Proceed to `/workflows:brainstorm`" -- hand off to brainstorm + 3. "Done for now" + +### Research Insights: Workflow Command + +**Orchestration vs. process knowledge separation:** The workflow command should handle ONLY flow control (which phase, what input). Skills handle "how to do the work." Move any logic about transcript format guidance, tag instructions, or processing methodology into the corresponding skill. ([Source: brainstorming evaluator]) + +**Graceful exit handling:** Each skill should have a stated exit condition. The workflow command should handle the case where a skill completes without producing output (user abandoned or input was invalid) by returning to the handoff menu. ([Source: brainstorming evaluator]) + +**Single-transcript confirmation:** When exactly one unprocessed transcript exists, do not auto-select. Present it with confirmation: "Found 1 unprocessed transcript: `filename.md`. Process this one?" This follows the brainstorming skill's principle of validating assumptions explicitly. ([Source: brainstorming evaluator]) + +**Success criteria:** +- Phase transitions work with both menu selection and direct arguments +- Phase selection is lightweight (2-3 lines of status, then AskUserQuestion) +- Graceful handling of empty directories (no errors, clear guidance) +- Handoff has exactly 3 options (matching brainstorm pattern) + +#### Phase 3: Research Agent + +Create the agent for searching research artifacts. + +**Tasks:** + +- [x] Create `plugins/compound-engineering/agents/research/user-research-analyst.md` + - Frontmatter: + ```yaml + name: user-research-analyst + description: "Search research personas and interview insights for evidence relevant to the feature or task being planned. Use when planning user-facing features, evaluating design decisions, or brainstorming product improvements." + model: inherit + ``` + - **Note: The current year is 2026.** + - Role preamble: "You are an expert user research analyst specializing in surfacing relevant personas, insights, and opportunities from the team's research corpus." + - Include 3 `` blocks: + + ```xml + + + Context: User is planning a new feature for onboarding. + user: "I want to redesign the onboarding flow" + assistant: "I'll use the user-research-analyst agent to search for relevant personas and interview insights about onboarding experiences." + Since the user is planning a user-facing feature, search research artifacts for relevant personas and insights before proceeding. + + + Context: User is debugging a user-facing issue with exports. + user: "Users are complaining about the export feature being hard to find" + assistant: "Let me use the user-research-analyst agent to find any interview insights about export workflows and pain points." + The user is investigating a UX problem. Search research for relevant behavioral observations and workarounds. + + + Context: User is brainstorming improvements to the dashboard. + user: "We want to make the dashboard more useful for our customers" + assistant: "I'll use the user-research-analyst agent to surface relevant personas, their dashboard usage patterns, and identified opportunities." + The user is exploring improvements to a user-facing feature. Research insights will ground the brainstorm in evidence. + + + ``` + + - Grep-first search strategy: + 1. Extract keywords from feature/task description + 2. Grep pre-filter `docs/research/personas/` and `docs/research/interviews/` in parallel (case-insensitive) + 3. Read frontmatter of matched files (limit: 30 lines) + 4. Score relevance based on keyword overlap with tags, role, opportunities + 5. Full read of relevant files only (opportunities are in body content, not frontmatter -- grep body for opportunity keywords) + 6. Return distilled summaries + 7. **Fallback:** If grep returns fewer than 3 candidates, do a broader content search across all files + 8. **Always check:** Read the most recent persona files regardless of keyword match (they are the primary synthesis artifacts) + + - Structured output format following `learnings-researcher` pattern (adapt format during PR 2 integration as needed): + ``` + ## User Research Findings + + ### Search Context + - Feature/Task: [description] + - Keywords Used: [tags, roles, topics searched] + - Files Scanned: [X personas, Y interviews] + - Relevant Matches: [Z files] + + ### Relevant Personas + #### [Persona Name] (confidence: high/medium/low) + - Role: [role] + - Key Insight: [most relevant finding for this task] + - Relevant Opportunities: [from opportunities table] + - Source Interviews: [list] + + ### Key Quotes + - "[quote]" -- [participant_id], [context] + + ### Research Gaps + - [Areas where research coverage is thin or missing] + + ### Recommendations + - [Specific actions based on research findings] + ``` + + - Handle empty `docs/research/` gracefully: return "No user research data found. Run `/workflows:research` to start building your research corpus." + - DO/DON'T efficiency guidelines matching `learnings-researcher` pattern + - **Integration Points** section at bottom: "Intended callers (to be wired in PR 2): `/workflows:brainstorm` Phase 1.1, `/workflows:plan` Step 1. Will run in parallel with `learnings-researcher` and `repo-research-analyst`." + +### Research Insights: Agent + +**Opportunities require body grep:** The `opportunities` data lives in persona document body tables, not frontmatter. The agent spec must note that opportunity searching requires body content grep, not just frontmatter grep. ([Source: architecture-strategist]) + +**Invocation interface:** Will be invoked as `Task user-research-analyst(feature_description)` following the same pattern as `Task learnings-researcher(feature_description)`. ([Source: architecture-strategist]) + +**Success criteria:** +- Agent follows grep-first pattern with fallback for sparse results +- Output format is structured and machine-consumable (for PR 2 integration) +- Handles empty research directories without errors +- Examples clearly demonstrate when to invoke +- Uses `model: inherit` per v2.23.1 policy + +#### Phase 4: Metadata Updates + +Update all plugin metadata files with correct counts. **Note:** Fix pre-existing count drift in README (currently says 25 commands / 16 skills, actually 24 / 18) and marketplace.json version drift (2.31.0 vs plugin.json 2.31.1). + +**Tasks:** + +- [x] Update `plugins/compound-engineering/.claude-plugin/plugin.json` + - Bump version from `2.31.1` to `2.32.0` (MINOR: new components) + - Update description: `"AI-powered development tools. 30 agents, 25 commands, 21 skills, 1 MCP server for code review, research, design, and workflow automation."` + +- [x] Update `.claude-plugin/marketplace.json` + - Update compound-engineering plugin description: `"Includes 30 specialized agents, 25 commands, and 21 skills."` + - Update version to `2.32.0` (fixes pre-existing drift from 2.31.0) + +- [x] Update `plugins/compound-engineering/README.md` + - **Fix pre-existing count errors** (currently says 25 commands, 16 skills) + - Update component count table: Agents 30, Commands 25, Skills 21 + - Add to Research agents table (currently 5, becomes 6): + ``` + | `user-research-analyst` | Search research artifacts for relevant personas and insights | + ``` + - Update Research section header count: "Research (6)" + - Add to Workflow Commands table: + ``` + | `/workflows:research` | Plan research, process transcripts, and build personas | + ``` + - Add new "User Research" skill category with 3 entries: + ``` + ### User Research + | Skill | Description | + |-------|-------------| + | `research-plan` | Create structured research plans with outcome-focused objectives | + | `transcript-insights` | Process interview transcripts into structured snapshots and insights | + | `persona-builder` | Synthesize insights across interviews into living persona documents | + ``` + +- [x] Update `plugins/compound-engineering/CHANGELOG.md` + - Add exact entry: + ```markdown + ## [2.32.0] - 2026-02-11 + + ### Added + + - **`/workflows:research` command** - Plan user research, process interview transcripts, and build personas from accumulated insights + - **`research-plan` skill** - Create structured research plans with outcome-focused objectives and story-based discussion guides + - **`transcript-insights` skill** - Process interview transcripts into structured snapshots with tagged insights and experience maps + - **`persona-builder` skill** - Synthesize insights across interviews into living persona documents with confidence tracking + - **`user-research-analyst` agent** - Search research artifacts for relevant personas and insights (not yet wired into brainstorm/plan workflows -- see PR 2) + - **Discovery playbook reference** - Bundled Continuous Product Discovery Playbook (Teresa Torres + Mom Test methodology) as `references/discovery-playbook.md` in each research skill + ``` + +**Success criteria:** +- All four files updated with matching counts +- Version bumped consistently to 2.32.0 across plugin.json and marketplace.json +- Pre-existing README count errors corrected +- README tables include all new components in correct categories +- CHANGELOG follows Keep a Changelog format with exact entry above + +#### Phase 5: Verification + +Validate everything is correct before committing. + +**Tasks:** + +- [x] Count components match descriptions: + ```bash + ls plugins/compound-engineering/agents/**/*.md | wc -l # Should be 30 + ls plugins/compound-engineering/commands/**/*.md | wc -l # Should be 25 + ls -d plugins/compound-engineering/skills/*/ | wc -l # Should be 21 + ``` + +- [x] Validate JSON files: + ```bash + cat .claude-plugin/marketplace.json | jq . + cat plugins/compound-engineering/.claude-plugin/plugin.json | jq . + ``` + +- [x] Verify no bare backtick references in skills: + ```bash + grep -E '`(references|assets|scripts)/[^`]+`' plugins/compound-engineering/skills/research-plan/SKILL.md + grep -E '`(references|assets|scripts)/[^`]+`' plugins/compound-engineering/skills/transcript-insights/SKILL.md + grep -E '`(references|assets|scripts)/[^`]+`' plugins/compound-engineering/skills/persona-builder/SKILL.md + # All three should return nothing + ``` + +- [x] Verify description counts match across files: + ```bash + grep "30.*agents" plugins/compound-engineering/.claude-plugin/plugin.json + grep "25 commands" plugins/compound-engineering/.claude-plugin/plugin.json + grep "21 skills" plugins/compound-engineering/.claude-plugin/plugin.json + ``` + +- [x] Verify discovery playbook exists in all three skill directories and is identical: + ```bash + ls plugins/compound-engineering/skills/research-plan/references/discovery-playbook.md + ls plugins/compound-engineering/skills/transcript-insights/references/discovery-playbook.md + ls plugins/compound-engineering/skills/persona-builder/references/discovery-playbook.md + md5 plugins/compound-engineering/skills/*/references/discovery-playbook.md + # All three checksums should be identical + ``` + +- [x] Verify interview frontmatter has separate role/company_type/source_transcript fields (spot-check SKILL.md templates) + +## Acceptance Criteria + +### Functional Requirements + +- [ ] `/workflows:research` presents a lightweight phase selection when run without arguments +- [ ] `/workflows:research plan` loads the research-plan skill and creates a plan document +- [ ] `/workflows:research process` loads transcript-insights skill and processes a transcript +- [ ] `/workflows:research personas` loads persona-builder skill and creates/updates a persona +- [ ] Directory setup creates `docs/research/` directories silently if they don't exist +- [ ] Phase selection shows brief artifact counts and recommends next logical phase +- [ ] Process phase lists unprocessed transcripts when no specific file is given +- [ ] Process phase confirms single-transcript selection (does not auto-select) +- [ ] Process phase handles "no transcripts exist" with clear guidance +- [ ] Personas phase handles "no interviews exist" with clear guidance +- [ ] Persona matching presents candidates with context (name, interview count, confidence) and asks user to confirm +- [ ] Persona merge follows field-by-field update rules (see Persona Merge Specification) +- [ ] Contradicting interview data produces a Divergences section (not silent count updates) +- [ ] Each phase ends with a 3-option handoff menu (continue research, brainstorm, done) +- [ ] All three skills include `## Human Review Checklist` in output +- [ ] All three skills reference `discovery-playbook.md` with proper markdown links +- [ ] `user-research-analyst` agent returns structured output with personas, quotes, confidence levels, and gaps +- [ ] Agent handles empty `docs/research/` gracefully +- [ ] Interview snapshots output separate `role`, `company_type`, and `source_transcript` frontmatter fields + +### Non-Functional Requirements + +- [ ] All skills use imperative voice (no "you should") +- [ ] All YAML frontmatter follows established patterns +- [ ] No bare backtick references to files in `references/` +- [ ] Agent uses `model: inherit` per v2.23.1 policy +- [ ] Agent uses grep-first search strategy with fallback for sparse results +- [ ] Each skill includes year note ("The current year is 2026.") + +### Quality Gates + +- [ ] Component counts in plugin.json, marketplace.json, and README.md all match actual file counts +- [ ] Version bumped to 2.32.0 in both plugin.json and marketplace.json +- [ ] Pre-existing README count errors corrected +- [ ] CHANGELOG.md documents all changes with exact entry text +- [ ] JSON files pass `jq` validation +- [ ] Skill compliance checklist passes (from CLAUDE.md) +- [ ] Discovery playbook checksums match across all 3 skill directories + +## Success Metrics + +- All 5 new components created and follow established patterns +- Component counts accurate across all metadata files (including fixing pre-existing drift) +- Each skill produces well-structured output following the templates in the brainstorm +- The workflow command successfully orchestrates all three phases +- Research artifacts use consistent YAML frontmatter enabling future agent search +- Interview frontmatter supports reliable persona matching (separate fields, not composite strings) + +## Dependencies and Prerequisites + +- **Discovery playbook source file**: `~/Downloads/discovery-playbook.md` must exist (already verified) + +## Future Considerations + +- **PR 2**: Wire `user-research-analyst` into `/workflows:brainstorm` (Phase 1) and `/workflows:plan` (Step 1) to auto-surface research during planning +- **Experiment phase**: `/workflows:research experiment` to design validation approaches (A/B tests, metrics) +- **Cross-interview theming**: `docs/research/themes.md` tracking cross-cutting themes with evidence strength +- **Multi-persona attribution**: Allow interviews to be linked to multiple personas (primary + secondary) +- **Batch processing UX**: Group-then-confirm approach when multiple unlinked interviews exist +- **Tag governance**: Consider `docs/research/taxonomy.md` after sufficient usage establishes patterns + +## Documentation Plan + +- [ ] README.md updated with all new components (Phase 4) +- [ ] CHANGELOG.md documents v2.32.0 changes (Phase 4) +- [ ] Run `claude /release-docs` after merging to update documentation site + +## References and Research + +### Internal References + +- Brainstorm: `docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md` +- Workflow command pattern: `plugins/compound-engineering/commands/workflows/brainstorm.md` +- Skill pattern: `plugins/compound-engineering/skills/brainstorming/SKILL.md` +- Agent pattern: `plugins/compound-engineering/agents/research/learnings-researcher.md` +- Plugin CLAUDE.md: `plugins/compound-engineering/CLAUDE.md` (versioning, compliance checklist) +- Root CLAUDE.md: `CLAUDE.md` (component update checklist) +- Institutional learning: `docs/solutions/plugin-versioning-requirements.md` + +### External References + +- Teresa Torres, *Continuous Discovery Habits* -- interview snapshots, OST, story-based interviewing +- Rob Fitzpatrick, *The Mom Test* -- past behavior focus, no pitching +- Discovery playbook: `~/Downloads/discovery-playbook.md` (bundled as reference) +- [AI-Assisted Qualitative Analysis Guide (SAGE, 2025)](https://journals.sagepub.com/doi/10.1177/16094069251354863) -- Human review requirements for AI-generated research +- [What we learned from creating a tagging taxonomy (Dovetail)](https://dovetail.com/blog/what-we-learned-creating-tagging-taxonomy/) -- Tag taxonomy design +- [3 Persona Types (NNGroup)](https://www.nngroup.com/articles/persona-types/) -- Confidence/sample size norms +- [Taxonomy for UX Research Repository (Condens)](https://condens.io/taxonomy-for-ux-research-repository/) -- Two-tier tag structure + +## Key Decisions Log + +| # | Decision | Rationale | +|---|----------|-----------| +| 1 | Workflow command with 3 phases | Matches existing `workflows:brainstorm` pattern | +| 2 | Three modular skills | Each phase is independently useful; follows plugin's specialized tool pattern | +| 3 | Discovery playbook duplicated per skill | Follows established convention (every skill has its own `references/`). 3x maintenance cost documented. | +| 4 | Separate `role` + `company_type` fields in interview frontmatter | Required for reliable persona matching. Composite strings cause impedance mismatch. | +| 5 | `source_transcript` field in interview frontmatter | Enables unprocessed transcript detection without fragile filename matching. | +| 6 | Two-tier tag taxonomy (type + topic) | Type tags (6 fixed values) enable structured analysis; topic tags enable free-form discovery. Grounded in Dovetail/Condens best practices. | +| 7 | Persona merge requires user confirmation with context | Prevents incorrect persona corruption; shows name, count, confidence in prompt. | +| 8 | Persona Divergences section for contradictions | Contradictions are normal in qualitative research -- silent count updates are misleading. | +| 9 | Confidence thresholds: 1=low, 2-3=medium, 4+=high | Adjusted from original (2-4=medium) per qualitative research norms. Teresa Torres recommends at least 3 for credible patterns. | +| 10 | Agent model: inherit | Per v2.23.1 policy. All agents use `model: inherit` except `lint`. | +| 11 | Lightweight phase selection (not "Smart Phase 0") | Reduced from full phase to brief status + AskUserQuestion. Matches brainstorm pattern simplicity. | +| 12 | 3-option handoff (not 5) | Matches brainstorm pattern. "Continue research" routes back to phase selection for sub-routing. | +| 13 | Human Review Checklist in all output | AI-generated quotes can be fabricated. Checklist ensures human verification of critical elements. | +| 14 | PR 1 scope: agent created but not wired in | Keeps PR focused; integration is a separate, lower-risk change. | +| 15 | PII note in skill docs | Recommend gitignoring transcripts directory; research ethics consideration. | diff --git a/docs/plans/2026-02-13-fix-research-process-first-action-plan.md b/docs/plans/2026-02-13-fix-research-process-first-action-plan.md new file mode 100644 index 00000000..995de2b1 --- /dev/null +++ b/docs/plans/2026-02-13-fix-research-process-first-action-plan.md @@ -0,0 +1,109 @@ +--- +title: "fix: Research process fails when transcript is first action" +type: fix +date: 2026-02-13 +--- + +# fix: Research process fails when transcript is first action + +## Overview + +`/workflows:research` stalls when a user tries to process a transcript as their first research action. Two cascading bugs: (1) Phase 2 doesn't handle inline transcript content, and (2) the transcript-insights skill has no empty-state handling for the plans directory. + +Related issue: EveryInc/compound-engineering-plugin#187 + +## Problem Statement + +When a user runs `/workflows:research process this transcript [content]` with empty research directories: + +1. Phase 2 checks `docs/research/transcripts/` for files → finds nothing → reports "no transcripts found" and exits +2. Even if the transcript were saved first, the transcript-insights skill tries to list research plans from an empty `docs/research/plans/` directory with no fallback + +The workflow command and the skill have **mismatched input handling** — the skill supports inline content (Step 1: "If content is pasted directly, proceed with that content") but the workflow command never passes inline content through. + +## Proposed Solution + +Two targeted edits to two files. No new files needed. + +### Fix 1: `plugins/compound-engineering/commands/workflows/research.md` + +**Location:** Phase 2: Process section (lines 82-114) + +**Change:** Add an inline content check before the file-based transcript check. Insert a new subsection before "### Check for Transcripts": + +```markdown +### Check for Inline Content + +If the research phase argument contains more than just the word "process" (i.e., transcript content was provided inline): +1. Extract the transcript content from the argument (everything after "process") +2. Generate a filename from the meeting title or date: `YYYY-MM-DD__transcript.md` +3. Save to `docs/research/transcripts/[filename]` +4. Skip the transcript selection step — proceed directly to "Process Selected Transcript" with this file path +``` + +Then update the existing "Check for Transcripts" section to say: + +```markdown +### Check for Transcripts + +**If inline content was already handled above, skip this section.** + +Look for `.md` files in `docs/research/transcripts/`. +[... rest unchanged ...] +``` + +### Fix 2: `plugins/compound-engineering/skills/transcript-insights/SKILL.md` + +**Location:** Step 2: Link to Research Plan (lines 31-40) + +**Change:** Add empty-state handling before the existing list instruction. Replace the current Step 2 opening with: + +```markdown +### Step 2: Link to Research Plan + +Check for files in `docs/research/plans/`. + +**If no plans exist:** +Skip the plan listing. Use AskUserQuestion to confirm: "No research plans found. This will be tagged as ad-hoc research. Continue?" +If confirmed, set `research_plan: ad-hoc` in frontmatter and proceed to Step 3. + +**If plans exist:** +List existing research plans by reading frontmatter from files in `docs/research/plans/`: +- Show title, date, and status for each plan +- Most recent first, cap at 7 entries +- Include "Ad-hoc / no plan" as the final option + +Use AskUserQuestion to ask which plan this transcript belongs to. Store the plan slug (filename without date prefix and extension) in the output frontmatter. + +If "Ad-hoc" is selected, set `research_plan: ad-hoc` in frontmatter. +``` + +## Acceptance Criteria + +- [x] `/workflows:research process this transcript [inline content]` saves transcript to file and processes it — even with empty research directories +- [x] `/workflows:research process` (no inline content) still works with existing file-based flow +- [x] transcript-insights skill handles empty `docs/research/plans/` gracefully by defaulting to ad-hoc +- [x] transcript-insights skill still lists plans when they exist +- [x] No changes to brainstorm, plan, or other workflow commands + +## Files to Edit + +| File | Lines | Change | +|------|-------|--------| +| `plugins/compound-engineering/commands/workflows/research.md` | 82-90 | Add inline content handling before file check | +| `plugins/compound-engineering/skills/transcript-insights/SKILL.md` | 31-40 | Add empty-state handling for plans directory | + +## Plugin Metadata Updates + +This is a patch fix (no new components), so: + +- [x] Bump patch version in `plugins/compound-engineering/.claude-plugin/plugin.json` +- [x] Add CHANGELOG entry under `### Fixed` +- [x] No README or marketplace.json changes needed (component counts unchanged) + +## References + +- Issue: EveryInc/compound-engineering-plugin#187 +- Workflow command: `plugins/compound-engineering/commands/workflows/research.md:82-114` +- Skill: `plugins/compound-engineering/skills/transcript-insights/SKILL.md:31-40` +- Good empty-state pattern: `plugins/compound-engineering/agents/research/user-research-analyst.md` (Step 8) diff --git a/docs/research/interviews/.gitkeep b/docs/research/interviews/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/research/personas/.gitkeep b/docs/research/personas/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/research/plans/.gitkeep b/docs/research/plans/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/research/transcripts/.gitkeep b/docs/research/transcripts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/solutions/integration-issues/adding-optional-workflow-phases-with-graceful-degradation.md b/docs/solutions/integration-issues/adding-optional-workflow-phases-with-graceful-degradation.md new file mode 100644 index 00000000..376a2482 --- /dev/null +++ b/docs/solutions/integration-issues/adding-optional-workflow-phases-with-graceful-degradation.md @@ -0,0 +1,178 @@ +--- +title: "Adding optional workflow phases with graceful degradation" +date: 2026-02-13 +category: integration-issues +tags: + - workflow-orchestration + - privacy-by-design + - feature-integration + - graceful-degradation + - deduplication + - plugin-development +severity: medium +component: workflows +solution_type: pattern +--- + +# Adding Optional Workflow Phases with Graceful Degradation + +## Problem + +When adding a new optional workflow phase (Research) that feeds into existing phases (Brainstorm, Plan), four integration problems surfaced during review: + +1. **PII in sample data** — real names, company names, and confidential discussions were committed to a public-facing repo as sample research artifacts +2. **Reference file duplication** — a 414-line reference file was copied identically into 3 skill directories (~30% of the PR's line count) +3. **Noisy degradation** — the integration into brainstorm/plan workflows could mention missing research data to ALL users, not just those who opted into research +4. **Weak privacy language** — skills said "Consider adding transcripts to .gitignore" instead of "MUST NOT commit" + +## Solution 1: "Do No Harm" Integration Pattern + +When adding an optional agent to existing workflows, two layers of graceful degradation are needed: + +**Layer 1 — The agent handles empty data:** +```markdown +## Step 8: Handle Empty Research Directory + +If `docs/research/` does not exist or contains no files, return: +"No user research data found." +``` + +**Layer 2 — The calling workflow skips silently:** +```markdown +If `user-research-analyst` returns relevant findings (personas, insights, +opportunities), briefly summarize them before starting the collaborative +dialogue. If no research data exists, skip the summary silently and proceed +directly to the collaborative dialogue — do not mention the absence of +research or suggest running `/workflows:research`. +``` + +The agent that produces optional data handles the "no data" case with a message. The workflows that consume optional data handle it with **silence**. This prevents cascading "you should do research" messages. + +**Implementation pattern:** +- Run the new agent in **parallel** with existing agents (no serial bottleneck) +- Use conditional language in the consuming workflow: "If findings were returned... If not, skip silently" +- Explicitly instruct "do not mention the absence" to prevent well-meaning suggestions + +## Solution 2: PII-Safe Research Artifacts + +Raw interview transcripts contain PII and must never reach version control. + +**File structure:** +``` +docs/research/ +├── plans/ # Committed — research plans with hypotheses +├── transcripts/ # GITIGNORED — raw interview data with PII +├── interviews/ # Committed — anonymized snapshots (user-001, user-002) +└── personas/ # Committed — synthesized persona documents +``` + +**Key rules:** +- `.gitignore` must include `docs/research/transcripts/*.md` BEFORE any transcripts are created +- Skills must give explicit PII stripping instructions: replace names inline in quotes, anonymize company names, sanitize filenames +- Use "MUST NOT be committed to public repositories" — not "consider" or "should" +- Sample data for testing must use synthetic data, never real interview content + +**What went wrong:** Sample data files were created with real names ("Krista," "Holly," "Beth"), real companies ("WellCare," "Centene," "Highmark"), and confidential personnel discussions. These were committed to the branch and only caught during code review. + +## Solution 3: Reference File Deduplication + +When multiple skills need the same reference material, maintain ONE canonical copy. + +**Before (3 copies, 1,242 lines):** +``` +skills/ +├── research-plan/references/discovery-playbook.md # 414 lines +├── transcript-insights/references/discovery-playbook.md # 414 lines (duplicate) +└── persona-builder/references/discovery-playbook.md # 414 lines (duplicate) +``` + +**After (1 copy, 414 lines):** +``` +skills/ +├── research-plan/references/discovery-playbook.md # 414 lines (canonical) +├── transcript-insights/SKILL.md # references ../research-plan/references/ +└── persona-builder/SKILL.md # references ../research-plan/references/ +``` + +In each non-canonical SKILL.md: +```markdown +**Reference:** [discovery-playbook.md](../research-plan/references/discovery-playbook.md) +``` + +Relative paths work because Claude Code follows markdown links when loading skill context. + +## Solution 4: Phase Recommendation Priority + +When a workflow command recommends the next phase, prioritize actionable data over missing prerequisites. + +**Wrong order:** +``` +- No plans exist → recommend Plan +- Unprocessed transcripts exist → recommend Process +``` + +**Right order:** +``` +- Unprocessed transcripts exist → recommend Process (ready-to-process data takes priority) +- Interviews exist but no personas → recommend Personas +- No plans and no transcripts → recommend Plan +``` + +Users who drop a transcript into the folder and run `/workflows:research` should be guided to process it — not steered back to create a plan first. Always offer an ad-hoc option (`research_plan: ad-hoc`) so no phase is a hard prerequisite for another. + +## Prevention Strategies + +### 1. PII in Sample Data + +**Prevention:** Create `.gitignore` entries for data directories BEFORE creating the directories. Use only synthetic data in committed samples. + +**Checklist item:** `[ ] All sample data uses fictional names/companies only (no real PII)` + +**Detection:** `grep -riE '[A-Z][a-z]+ (said|mentioned|discussed)' docs/research/` in pre-commit or CI. + +### 2. Reference File Duplication + +**Prevention:** Before copying a reference file into a second skill, stop and use a relative path instead. + +**Checklist item:** `[ ] No reference files duplicated across skills (use relative paths to canonical copy)` + +**Detection:** `find plugins/compound-engineering/skills -name "*.md" -exec md5sum {} \; | sort | uniq -w32 -d` + +### 3. "Do No Harm" Not Verified Until Review + +**Prevention:** When modifying brainstorm/plan/work workflows, explicitly test with an empty `docs/research/` directory and confirm zero behavioral change. + +**Checklist item:** `[ ] Workflow changes verified to produce no output difference when optional data is absent` + +**Detection:** Run the modified workflow in a fresh repo without the feature's data. Confirm no new prompts, messages, or suggestions appear. + +### 4. Weak Privacy Language + +**Prevention:** Use RFC 2119 language: MUST/MUST NOT for security and privacy requirements. Never use "consider," "should," or "recommended" for PII handling. + +**Checklist item:** `[ ] Privacy/security requirements use MUST/MUST NOT language (not "consider" or "should")` + +**Detection:** `grep -rn 'consider.*gitignore\|should.*PII\|recommended.*privacy' skills/` + +## Related Documentation + +- `docs/solutions/plugin-versioning-requirements.md` — Plugin versioning and multi-file update patterns +- `plugins/compound-engineering/CLAUDE.md` — Plugin development conventions, skill compliance checklist +- `docs/brainstorms/2026-02-13-user-research-workflow-integration-brainstorm.md` — Integration design decisions +- `docs/brainstorms/2026-02-10-user-research-workflow-brainstorm.md` — Original workflow design + +## Files Modified + +| File | Change | +|------|--------| +| `commands/workflows/brainstorm.md` | Added `user-research-analyst` to Phase 1.1 with silent degradation | +| `commands/workflows/plan.md` | Added `user-research-analyst` to Step 1 and Step 1.6 with conditional inclusion | +| `commands/workflows/research.md` | Fixed phase recommendation to prioritize unprocessed transcripts | +| `agents/research/user-research-analyst.md` | Removed "to be wired in PR 2" TODO, updated Integration Points | +| `skills/transcript-insights/SKILL.md` | Strengthened PII guidance from "Consider" to "MUST NOT" | +| `skills/persona-builder/SKILL.md` | Simplified evidence strength/hypothesis status tables; deduplicated playbook reference | +| `.gitignore` | Added `docs/research/transcripts/*.md` | + +## Key Takeaway + +The pattern for adding optional workflow phases: **the producer handles absence with a message; the consumer handles absence with silence.** This ensures the feature enhances workflows for adopters without degrading them for everyone else. diff --git a/docs/solutions/integration-issues/workflow-skill-transcript-input-mismatch.md b/docs/solutions/integration-issues/workflow-skill-transcript-input-mismatch.md new file mode 100644 index 00000000..f0dd6b1b --- /dev/null +++ b/docs/solutions/integration-issues/workflow-skill-transcript-input-mismatch.md @@ -0,0 +1,128 @@ +--- +title: "/workflows:research process stalls on inline transcript with empty plans directory" +date: 2026-02-13 +category: integration-issues +tags: [workflow-automation, research-workflow, transcript-processing, state-handling, first-use-failure] +severity: high +component: plugins/compound-engineering/commands/workflows/research.md + plugins/compound-engineering/skills/transcript-insights/SKILL.md +resolution_time: 30 minutes +--- + +# /workflows:research process stalls on inline transcript with empty plans directory + +## Problem + +`/workflows:research process this transcript [content]` stalls when used as the first research action. Claude creates directories but never produces output. Brainstorm and plan workflows are unaffected. + +**Symptom:** The model appears stuck after creating `docs/research/` directories. No transcript is saved, no interview snapshot is generated. + +**Trigger:** Empty research directories (no prior transcripts, plans, or interviews). + +## Root Cause + +Two cascading bugs at the integration boundary between the workflow command and its downstream skill: + +**Bug 1: Workflow command doesn't pass inline content to the skill.** +Phase 2 of `research.md` only checks for `.md` files in `docs/research/transcripts/`. When the directory is empty, it reports "no transcripts found" and exits. The `transcript-insights` skill supports inline content (Step 1: "If content is pasted directly, proceed"), but the workflow command never provides a path for inline content to reach the skill. + +**Bug 2: Skill stalls on empty plans directory.** +Even if Bug 1 were fixed, `transcript-insights` Step 2 tries to list research plans from `docs/research/plans/` with no empty-state fallback. On first use, the directory is empty and the model stalls trying to reconcile the instruction to "list plans" with nothing to list. + +**Pattern:** This is a "first-use failure" — everything works once artifacts exist from prior runs, but the first invocation with empty directories fails. + +## Solution + +### Fix 1: research.md — Add inline content handling + +Added a "Check for Inline Content" section before "Check for Transcripts" in Phase 2: + +```markdown +### Check for Inline Content + +If the research phase argument contains more than just the word "process" +(i.e., transcript content was provided inline): + +1. Extract the transcript content from the argument (everything after "process") +2. Look for a meeting title or date in the content to generate a filename. + Use the format: YYYY-MM-DD__transcript.md +3. Save the content to docs/research/transcripts/[filename] +4. Skip the transcript selection step — proceed directly to Process Selected Transcript +``` + +Updated "Check for Transcripts" with a guard: "If inline content was already saved above, skip this section." Also updated the error message to mention the inline option. + +### Fix 2: transcript-insights/SKILL.md — Add empty-state handling + +Replaced the unconditional plan listing in Step 2 with: + +```markdown +Check for files in docs/research/plans/. + +**If no plans exist:** +Set research_plan: ad-hoc in frontmatter and proceed to Step 3. + +**If plans exist:** +List existing research plans... +[existing flow unchanged] +``` + +Removed the AskUserQuestion confirmation for empty state — the user already committed to processing by providing a transcript. Just default to ad-hoc silently. + +## Why It Works + +- **Inline content becomes first-class:** The workflow now extracts, saves, and passes inline content through to the skill, matching what the skill already documented as supported input. +- **Empty state is a non-event:** When no plans exist, the skill defaults to ad-hoc without blocking. The user can create plans later. +- **Backward compatible:** The existing file-based flow is untouched. The inline path only activates when the argument contains more than "process". +- **Converges at the same point:** Both the inline and file-based paths meet at "Process Selected Transcript" with a file path, so all downstream logic is shared. + +## Why Other Workflows Were Unaffected + +| Workflow | Why it works | +|----------|-------------| +| `/workflows:brainstorm` | Accepts inline descriptions directly — no file dependency | +| `/workflows:plan` | Has explicit fallback: "If no brainstorm found, run idea refinement" | +| `/workflows:research` (phase menu) | Just counts files — 0 is valid | +| `/workflows:research plan` | Creates from scratch — no dependency on existing artifacts | +| `/workflows:research personas` | Explicitly handles empty state: "No processed interviews found" | + +## Prevention: First-Use Failure Checklist + +This class of bug happens when workflow commands and skills have mismatched input handling or missing empty-state fallbacks. When writing new workflow commands or skills, check: + +### Input Contract +- [ ] Every supported input format (file path, inline content, empty) is documented in both the workflow command AND the skill +- [ ] If a skill says it accepts inline content, the workflow command has a path to pass it through +- [ ] Empty input is handled explicitly (not silently ignored) + +### Empty-State Handling +- [ ] Every instruction that reads from a directory has an "If empty" branch +- [ ] Empty-state messages guide the user to a next action (not just "not found") +- [ ] Default behavior exists for first-use (e.g., ad-hoc tagging, skip to next step) + +### First-Run Test +- [ ] Can a user run this workflow with NO prior artifacts and succeed? +- [ ] All directories are created upfront (mkdir -p in Directory Setup) +- [ ] File selection handles 0, 1, and N files explicitly + +### Integration Boundary +- [ ] Workflow command documents what it passes to the skill +- [ ] Skill documents what it expects to receive +- [ ] Return contract is documented (what file gets created, what frontmatter fields) + +**Core insight:** Design workflows for the worst case (empty, first-run) first, then optimize for the common case (existing artifacts). + +## Files Changed + +| File | Change | +|------|--------| +| `plugins/compound-engineering/commands/workflows/research.md` | Added inline content handling before file check | +| `plugins/compound-engineering/skills/transcript-insights/SKILL.md` | Added empty-state handling for plans directory | +| `plugins/compound-engineering/.claude-plugin/plugin.json` | Version 2.32.0 → 2.32.1 | +| `plugins/compound-engineering/CHANGELOG.md` | Added Fixed section for 2.32.1 | + +## References + +- Issue: [EveryInc/compound-engineering-plugin#187](https://github.com/EveryInc/compound-engineering-plugin/issues/187) +- Fix plan: `docs/plans/2026-02-13-fix-research-process-first-action-plan.md` +- Original feature plan: `docs/plans/2026-02-11-feat-user-research-workflow-plan.md` +- Plugin versioning guide: `docs/solutions/plugin-versioning-requirements.md` diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index 9b35c5a7..f145c8a1 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", - "version": "2.34.0", - "description": "AI-powered development tools. 29 agents, 22 commands, 19 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.35.0", + "description": "AI-powered development tools. 30 agents, 23 commands, 22 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index 6819c484..f34255c6 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,29 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.35.0] - 2026-02-16 + +### Added + +- **`/workflows:research` command** - Plan user research, process interview transcripts, and build personas from accumulated insights +- **`research-plan` skill** - Create structured research plans with outcome-focused objectives and story-based discussion guides +- **`transcript-insights` skill** - Process interview transcripts into structured snapshots with tagged insights and experience maps +- **`persona-builder` skill** - Synthesize insights across interviews into living persona documents with confidence tracking +- **`user-research-analyst` agent** - Search research artifacts for relevant personas and insights +- **Discovery playbook reference** - Bundled Continuous Product Discovery Playbook (Teresa Torres + Mom Test methodology) + +### Changed + +- **`/workflows:brainstorm`** - Now runs `user-research-analyst` in parallel; silently skips when no research data exists +- **`/workflows:plan`** - Research context integrated into Step 1.6 consolidation + +### Fixed + +- **`/workflows:research` command** — Process phase now handles inline transcript content (saves to file before processing) instead of requiring pre-existing files in `docs/research/transcripts/` +- **`transcript-insights` skill** — Step 2 (Link to Research Plan) now gracefully handles empty `docs/research/plans/` directory by defaulting to ad-hoc instead of stalling + +--- + ## [2.34.0] - 2026-02-14 ### Added diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index ec1ad83b..db6bc6b5 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -6,9 +6,9 @@ AI-powered development tools that get smarter with every use. Make each unit of | Component | Count | |-----------|-------| -| Agents | 29 | -| Commands | 22 | -| Skills | 19 | +| Agents | 30 | +| Commands | 23 | +| Skills | 22 | | MCP Servers | 1 | ## Agents @@ -35,7 +35,7 @@ Agents are organized into categories for easier discovery. | `schema-drift-detector` | Detect unrelated schema.rb changes in PRs | | `security-sentinel` | Security audits and vulnerability assessments | -### Research (5) +### Research (6) | Agent | Description | |-------|-------------| @@ -44,6 +44,7 @@ Agents are organized into categories for easier discovery. | `git-history-analyzer` | Analyze git history and code evolution | | `learnings-researcher` | Search institutional learnings for relevant past solutions | | `repo-research-analyst` | Research repository structure and conventions | +| `user-research-analyst` | Search research artifacts for relevant personas and insights | ### Design (3) @@ -79,6 +80,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in |---------|-------------| | `/workflows:brainstorm` | Explore requirements and approaches before planning | | `/workflows:plan` | Create implementation plans | +| `/workflows:research` | Plan research, process transcripts, and build personas | | `/workflows:review` | Run comprehensive code reviews | | `/workflows:work` | Execute work items systematically | | `/workflows:compound` | Document solved problems to compound team knowledge | @@ -155,6 +157,14 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in |-------|-------------| | `agent-browser` | CLI-based browser automation using Vercel's agent-browser | +### User Research + +| Skill | Description | +|-------|-------------| +| `research-plan` | Create structured research plans with outcome-focused objectives | +| `transcript-insights` | Process interview transcripts into structured snapshots and insights | +| `persona-builder` | Synthesize insights across interviews into living persona documents | + ### Image Generation | Skill | Description | diff --git a/plugins/compound-engineering/agents/research/user-research-analyst.md b/plugins/compound-engineering/agents/research/user-research-analyst.md new file mode 100644 index 00000000..fe8ed4b4 --- /dev/null +++ b/plugins/compound-engineering/agents/research/user-research-analyst.md @@ -0,0 +1,176 @@ +--- +name: user-research-analyst +description: "Search research personas and interview insights for evidence relevant to the feature or task being planned. Use when planning user-facing features, evaluating design decisions, or brainstorming product improvements." +model: inherit +--- + + + +Context: User is planning a new feature for onboarding. +user: "I want to redesign the onboarding flow" +assistant: "I'll use the user-research-analyst agent to search for relevant personas and interview insights about onboarding experiences." +Since the user is planning a user-facing feature, search research artifacts for relevant personas and insights before proceeding. + + +Context: User is debugging a user-facing issue with exports. +user: "Users are complaining about the export feature being hard to find" +assistant: "Let me use the user-research-analyst agent to find any interview insights about export workflows and pain points." +The user is investigating a UX problem. Search research for relevant behavioral observations and workarounds. + + +Context: User is brainstorming improvements to the dashboard. +user: "We want to make the dashboard more useful for our customers" +assistant: "I'll use the user-research-analyst agent to surface relevant personas, their dashboard usage patterns, and identified opportunities." +The user is exploring improvements to a user-facing feature. Research insights will ground the brainstorm in evidence. + + + +**Note: The current year is 2026.** + +You are an expert user research analyst specializing in surfacing relevant personas, insights, and opportunities from the team's research corpus. Your mission is to find and distill applicable research findings before feature work begins, grounding product decisions in user evidence. + +## Search Strategy (Grep-First Filtering) + +The `docs/research/` directory contains personas and interview snapshots with YAML frontmatter. Use this efficient strategy to find relevant research: + +### Step 1: Extract Keywords from Feature Description + +From the feature/task description, identify: +- **User activities**: e.g., "dashboard", "export", "onboarding", "reporting" +- **User roles**: e.g., "manager", "analyst", "founder" +- **Pain indicators**: e.g., "slow", "confusing", "hard to find", "broken" +- **Workflow terms**: e.g., "morning routine", "weekly review", "sharing" + +### Step 2: Grep Pre-Filter (Critical for Efficiency) + +Run multiple Grep calls in parallel across both research directories: + +```bash +# Search personas (run in PARALLEL, case-insensitive) +Grep: pattern="[keyword]" path=docs/research/personas/ output_mode=files_with_matches -i=true +Grep: pattern="tags:.*(keyword1|keyword2)" path=docs/research/interviews/ output_mode=files_with_matches -i=true +Grep: pattern="role:.*(keyword)" path=docs/research/interviews/ output_mode=files_with_matches -i=true +Grep: pattern="focus:.*(keyword)" path=docs/research/interviews/ output_mode=files_with_matches -i=true +``` + +**Note:** Opportunities data lives in persona document body tables, not frontmatter. Search persona body content for opportunity keywords: +```bash +Grep: pattern="need.*[keyword]" path=docs/research/personas/ output_mode=files_with_matches -i=true +``` + +Combine results from all Grep calls to get candidate files. + +### Step 3: Read Frontmatter of Candidates + +For each candidate file, read the frontmatter (limit: 30 lines): + +```bash +Read: [file_path] with limit:30 +``` + +**For personas, extract:** name, role, company_type, interview_count, confidence, source_interviews +**For interviews, extract:** participant_id, role, company_type, focus, tags + +### Step 4: Score and Rank Relevance + +Match frontmatter fields against the feature/task description: + +**Strong matches (prioritize):** +- `role` or `tags` directly match feature keywords +- `focus` describes the relevant workflow +- Persona opportunities mention the feature area + +**Moderate matches (include):** +- Related roles or workflows +- Tags overlap with feature domain + +**Weak matches (skip):** +- No overlapping keywords, roles, or workflows + +### Step 5: Full Read of Relevant Files + +For files that pass the filter, read the complete document to extract: +- Relevant opportunities from the opportunities table +- Key quotes related to the feature +- Behavioral observations that inform design +- Divergences that indicate split user needs + +### Step 6: Always Check Recent Personas + +Regardless of keyword match results, read the most recent persona files (by `last_updated`). Personas are the primary synthesis artifacts and may contain broadly relevant insights not captured by keyword search. + +### Step 7: Fallback for Sparse Results + +If Grep returns fewer than 3 candidate files, do a broader content search: +```bash +Grep: pattern="[any feature keyword]" path=docs/research/ output_mode=files_with_matches -i=true +``` + +### Step 8: Handle Empty Research Directory + +If `docs/research/` does not exist or contains no files, return: +"No user research data found. Run `/workflows:research` to start building your research corpus." + +## Output Format + +```markdown +## User Research Findings + +### Search Context +- **Feature/Task:** [description] +- **Keywords Used:** [tags, roles, topics searched] +- **Files Scanned:** [X personas, Y interviews] +- **Relevant Matches:** [Z files] + +### Relevant Personas + +#### [Persona Name] (confidence: high/medium/low) +- **Role:** [role] +- **Key Insight:** [most relevant finding for this task] +- **Relevant Opportunities:** [from opportunities table] +- **Divergences:** [any split findings relevant to this feature] +- **Source Interviews:** [list] + +### Key Quotes +- "[quote]" -- [participant_id], [context] +- "[quote]" -- [participant_id], [context] + +### Behavioral Observations +- [Relevant behaviors, workarounds, or patterns from interviews] + +### Research Gaps +- [Areas where research coverage is thin or missing] +- [User roles or workflows not yet studied] + +### Recommendations +- [Specific actions based on research findings] +- [Suggested research to fill gaps before building] +``` + +## Efficiency Guidelines + +**DO:** +- Use Grep to pre-filter files BEFORE reading content +- Run multiple Grep calls in PARALLEL for different keywords +- Include body content Grep for opportunity keywords in personas +- Use `-i=true` for case-insensitive matching +- Always read recent persona files regardless of keyword match +- Do a broader Grep as fallback if fewer than 3 candidates found +- Distill findings into actionable insights +- Note research gaps explicitly + +**DON'T:** +- Read all files without pre-filtering +- Run Grep calls sequentially when they can be parallel +- Skip opportunity searching in persona body content +- Return raw document contents (distill instead) +- Include tangentially related findings +- Fabricate or extrapolate beyond what research data shows + +## Integration Points + +This agent is called by: +- `/workflows:brainstorm` Phase 1.1 -- surfaces research before brainstorming +- `/workflows:plan` Step 1 -- informs planning with user evidence + +Runs in parallel with `learnings-researcher` and `repo-research-analyst` during planning phases. diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index b4f3a0f6..d41be77a 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -37,14 +37,17 @@ Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough ### Phase 1: Understand the Idea -#### 1.1 Repository Research (Lightweight) +#### 1.1 Repository & User Research (Lightweight) -Run a quick repo scan to understand existing patterns: +Run these agents **in parallel** to understand existing patterns and user context: - Task repo-research-analyst("Understand existing patterns related to: ") +- Task user-research-analyst("Surface research relevant to: ") Focus on: similar features, established patterns, CLAUDE.md guidance. +If `user-research-analyst` returns relevant findings (personas, insights, opportunities), briefly summarize them before starting the collaborative dialogue. If no research data exists, skip the summary silently and proceed directly to the collaborative dialogue — do not mention the absence of research or suggest running `/workflows:research`. + #### 1.2 Collaborative Dialogue Use the **AskUserQuestion tool** to ask questions **one at a time**. diff --git a/plugins/compound-engineering/commands/workflows/plan.md b/plugins/compound-engineering/commands/workflows/plan.md index 631bccc6..f2f319af 100644 --- a/plugins/compound-engineering/commands/workflows/plan.md +++ b/plugins/compound-engineering/commands/workflows/plan.md @@ -76,10 +76,12 @@ Run these agents **in parallel** to gather local context: - Task repo-research-analyst(feature_description) - Task learnings-researcher(feature_description) +- Task user-research-analyst(feature_description) **What to look for:** - **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency - **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned) +- **User research:** relevant personas, interview insights, opportunities, and research gaps from `docs/research/` These findings inform the next step. @@ -114,6 +116,7 @@ After all research steps complete, consolidate findings: - Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`) - **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid) +- **If user research findings were returned**: include relevant personas and their relationship to this feature, key insights and quotes from interviews, research gaps (areas where coverage is thin). If no research data was found, skip this bullet silently. - Note external documentation URLs and best practices (if external research was done) - List related issues or PRs discovered - Capture CLAUDE.md conventions diff --git a/plugins/compound-engineering/commands/workflows/research.md b/plugins/compound-engineering/commands/workflows/research.md new file mode 100644 index 00000000..fdbb1a48 --- /dev/null +++ b/plugins/compound-engineering/commands/workflows/research.md @@ -0,0 +1,179 @@ +--- +name: workflows:research +description: Plan user research, process interview transcripts, and build personas from accumulated insights +argument-hint: "[plan|process|personas]" +--- + +# Research Workflow + +**Note: The current year is 2026.** Use this when dating research documents. + +Orchestrate the user research loop: plan studies, process interview transcripts, and synthesize personas from accumulated insights. + +## File Path Contracts + +All research artifacts follow these path conventions: + +| Artifact | Path Pattern | +|----------|-------------| +| Research plans | `docs/research/plans/YYYY-MM-DD--research-plan.md` | +| Transcripts | `docs/research/transcripts/*.md` (user-provided) | +| Interview snapshots | `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` | +| Personas | `docs/research/personas/.md` | + +## Directory Setup + +Create research directories if they do not exist: + +```bash +mkdir -p docs/research/plans docs/research/transcripts docs/research/interviews docs/research/personas +``` + +Run this silently before any phase. + +## Routing + + #$ARGUMENTS + +Read the content inside ``. Follow the FIRST matching rule below and STOP — do not continue to later rules. + +### Rule 1: Inline transcript content + +If the argument contains multi-line content (a transcript, meeting notes, interview text — anything beyond a single keyword or short phrase): + +This IS inline transcript content. Do NOT check artifact status. Do NOT show phase selection. Handle it immediately: + +1. Extract the meeting title and date from the content to generate a filename: `YYYY-MM-DD__transcript.md`. If no date is found, use today's date. +2. Save the full content to `docs/research/transcripts/[filename]` +3. Jump to **Process Selected Transcript** in Phase 2 below with this file path + +### Rule 2: Phase name keyword + +If the argument is exactly `plan`, `process`, or `personas`, jump to that phase below. + +### Rule 3: Unrecognized argument + +If the argument is a short unrecognized string, show the phase selection menu with a note: "Valid arguments: `plan`, `process`, `personas`." + +### Rule 4: Empty argument + +If the argument is empty, run phase selection: + +### Phase Selection + +**SKIP this section if Rule 1 matched above (inline content).** Only run this when the argument was empty. + +Show a brief artifact status (2-3 lines max): + +``` +Research status: +- N plans, N transcripts (M unprocessed), N interviews, N personas +``` + +**Counting unprocessed transcripts:** Count files in `docs/research/transcripts/`. Then check `docs/research/interviews/` frontmatter for `source_transcript` fields. Transcripts not referenced by any interview are unprocessed. Simpler fallback: count transcripts minus count of interviews. + +**Recommend the next logical phase** based on state: +- Unprocessed transcripts exist → recommend Process (ready-to-process data takes priority) +- Interviews exist but no personas → recommend Personas +- No plans and no transcripts → recommend Plan +- All phases have artifacts → show neutral menu + +Use **AskUserQuestion** with three options: +1. **Plan** -- Create a new research plan with objectives and discussion guide +2. **Process** -- Process an interview transcript into a structured snapshot +3. **Personas** -- Build or update personas from processed interviews + +Lead with the recommended option. + +--- + +## Phase 1: Plan + +Load the `research-plan` skill. + +The skill handles all research plan creation logic including objective framing, discussion guide generation, and output file creation. + +**Return contract:** The skill creates a file at `docs/research/plans/YYYY-MM-DD--research-plan.md`. + +After the skill completes, proceed to **Handoff**. + +--- + +## Phase 2: Process + +### Check for Inline Content + +If arriving here from **Rule 1** in Routing, the transcript has already been saved. Skip directly to **Process Selected Transcript** below. + +If the argument starts with "process" followed by substantial content, strip the "process" prefix, save the content as a transcript file (using the same naming logic from Rule 1), and skip to **Process Selected Transcript**. + +### Check for Transcripts + +**If inline content was already saved above, skip this section.** + +Look for `.md` files in `docs/research/transcripts/`. + +**If no transcripts exist:** +Report: "No transcripts found in `docs/research/transcripts/`. Save your interview transcript as a `.md` file there, or pass the content inline: `/workflows:research process [transcript content]`." +Proceed to **Handoff**. + +**If transcripts exist:** +Identify unprocessed transcripts (not yet referenced by any interview snapshot in `docs/research/interviews/`). + +**If no unprocessed transcripts:** +Report: "All transcripts have been processed. Add new transcripts to `docs/research/transcripts/` or re-process an existing one." +Proceed to **Handoff**. + +**If exactly one unprocessed transcript:** +Present it with confirmation via AskUserQuestion: "Found 1 unprocessed transcript: `[filename]`. Process this one?" +Do not auto-select. + +**If multiple unprocessed transcripts:** +List them and ask the user to select via AskUserQuestion. + +### Process Selected Transcript + +Load the `transcript-insights` skill with the selected transcript path. + +The skill handles all processing logic including plan linking, metadata gathering, insight extraction, and output file creation. + +**Return contract:** The skill creates a file at `docs/research/interviews/YYYY-MM-DD-participant-NNN.md`. + +After the skill completes, proceed to **Handoff**. + +--- + +## Phase 3: Personas + +### Check for Interviews + +Look for processed interviews in `docs/research/interviews/`. + +**If no interviews exist:** +Report: "No processed interviews found in `docs/research/interviews/`. Process transcripts first with `/workflows:research process`." +Proceed to **Handoff**. + +**If interviews exist:** +Load the `persona-builder` skill. + +The skill handles persona matching, creation, merging, and output file creation. + +**Return contract:** The skill creates or updates a file at `docs/research/personas/.md`. + +After the skill completes, proceed to **Handoff**. + +--- + +## Handoff + +Announce the created or updated file path. + +If the skill completed without producing output (user abandoned or input was invalid), skip the file announcement and proceed directly to the menu. + +Use **AskUserQuestion** with three options: + +1. **Continue research** -- Return to the phase selection menu +2. **Proceed to `/workflows:brainstorm`** -- Hand off to brainstorm workflow +3. **Done for now** + +If the user selects "Continue research", return to the **Phase Selection** section above. diff --git a/plugins/compound-engineering/skills/persona-builder/SKILL.md b/plugins/compound-engineering/skills/persona-builder/SKILL.md new file mode 100644 index 00000000..96ce83cd --- /dev/null +++ b/plugins/compound-engineering/skills/persona-builder/SKILL.md @@ -0,0 +1,251 @@ +--- +name: persona-builder +description: "Synthesize personas from processed interview snapshots with confidence tracking and evidence-backed opportunities. Use when processed interviews exist in docs/research/interviews/ or when building or updating personas." +--- + +# Persona Builder + +**Note: The current year is 2026.** + +Synthesize personas from processed interview snapshots. Personas are living documents that grow more confident as interviews accumulate. Follow evidence-based persona construction with confidence tracking, opportunity tables, and contradiction handling via Divergences sections. + +**Reference:** [discovery-playbook.md](../research-plan/references/discovery-playbook.md) -- Continuous Product Discovery Playbook with detailed methodology. + +## Quick Start + +1. Read processed interviews from `docs/research/interviews/` +2. Match to existing personas or create new ones +3. Generate or update a persona at `docs/research/personas/.md` + +## Instructions + +### Step 1: Read Available Interviews + +Scan `docs/research/interviews/` for processed interview snapshots. Read frontmatter (first 30 lines) of each file to extract: +- `participant_id` +- `role` +- `company_type` +- `focus` +- `tags` + +If no interviews exist, report: "No processed interviews found in `docs/research/interviews/`. Run `/workflows:research process` to create interview snapshots from transcripts." + +Present the user with a summary of available interviews and ask which one(s) to incorporate. If the user invoked this skill from the workflow command, a specific interview may already be identified. + +### Step 2: Match to Existing Personas + +After identifying the interview to incorporate: + +1. Extract `role` and `company_type` from the interview's frontmatter +2. Scan existing personas in `docs/research/personas/` for matches + +**Matching algorithm:** + +| Match Type | Criteria | Action | +|-----------|----------|--------| +| Exact match | Both `role` AND `company_type` match | Present as merge candidate | +| Partial match | `role` matches, `company_type` differs (or vice versa) | Present as possible candidate with differences highlighted | +| No match | Neither field matches | Offer to create new persona | +| Multiple matches | More than one persona matches | Present numbered list with differentiators | + +3. Present match results to the user via AskUserQuestion + +**Confirmation prompt must show:** +- Existing persona name, current interview count, confidence level +- 2-3 key characteristics of the existing persona +- The new interview's role, company type, and focus +- Option to "Create new persona" (always available) + +The user always confirms the choice. Never auto-merge. + +### Step 3a: Create New Persona + +If creating a new persona: + +1. Ask the user for a persona name (suggest a descriptive archetype name like "The Data-Driven Manager" or "The Hands-On Founder") +2. Build the persona from the selected interview(s) +3. Set `confidence: low` (single interview), `version: 1` +4. Write to `docs/research/personas/.md` + +Ensure the `docs/research/personas/` directory exists before writing. + +### Step 3b: Merge into Existing Persona + +If merging into an existing persona, follow the field-by-field update rules below. + +Read the full existing persona document before merging. + +## Merge Specification + +### Field-by-Field Update Rules + +| Field Category | Update Strategy | +|---------------|----------------| +| **Metadata** (`last_updated`, `interview_count`, `confidence`, `version`, `source_interviews`) | Always auto-update. Increment version, append participant_id to source_interviews, recalculate confidence. | +| **Persona name and role** | Preserve unless user explicitly requests change. | +| **Goals** | Append new goals not already listed. Flag potential duplicates with `[Review: possible overlap with Goal #N]`. | +| **Frustrations** | Append new frustrations. Flag potential duplicates with `[Review: possible overlap with Frustration #N]`. | +| **Behaviors** | Update participant counts as `(N/M participants)` where M = total interview count. When a behavior is NOT mentioned in the new interview, do NOT change its count (absence is not evidence). Add new behaviors. | +| **Quotes** | Add the single most representative new quote. Keep total at 5-7 max. If at cap, note "Additional quotes in source interviews." | +| **Opportunities table** | Add new rows. Update evidence strength counts for existing rows only when the new interview explicitly addresses that opportunity. | +| **Evidence section** | Always append new participant_id and research plan. | + +### Confidence Thresholds + +| Interview Count | Confidence Level | +|----------------|-----------------| +| 1 | low | +| 2-3 | medium | +| 4+ | high | + +### Contradiction Handling + +When a new interview contradicts an existing finding, do NOT silently update counts. Instead: + +1. Keep both data points with their evidence counts +2. Add to the `## Divergences` section: + +```markdown +## Divergences + +| Finding | Majority View | Minority View | Split | +|---------|--------------|---------------|-------| +| [Topic] | [View] (N/M) | [Contradicting view] (N/M) | N:N | +``` + +3. When divergences reach 40/60 split or closer, flag for potential persona segmentation: `[Flag: Consider splitting this persona -- [finding] shows near-even split]` +4. Surface contradictions in the merge confirmation prompt so the user is aware before confirming + +### Evidence Strength + +- **Weak**: Only 1 participant, or a small minority +- **Medium**: Roughly half of participants +- **Strong**: Most participants (clear majority) + +### Hypothesis Status + +- **SUPPORTED**: Most evidence supports +- **MIXED**: Evidence is split +- **CHALLENGED**: Most evidence contradicts +- **NEW**: Emerged from this interview, no prior evidence + +## Output Template + +```markdown +--- +name: "[Descriptive archetype name]" +role: "[Primary job title or function]" +company_type: "[Industry or company category]" +last_updated: YYYY-MM-DD +interview_count: N +confidence: low / medium / high +source_interviews: [user-001, user-003, user-005] +version: N +--- + +# [Persona Name] + +## Overview + +[2-3 paragraph narrative description of this persona -- who they are, what drives them, and how they work. Ground in evidence from interviews.] + +## Goals + +1. [Goal with evidence count] (N/M participants) +2. [Goal] (N/M participants) + +## Frustrations + +1. [Frustration with evidence count] (N/M participants) +2. [Frustration] (N/M participants) + +## Behaviors + +| Behavior | Frequency | Evidence | +|----------|-----------|----------| +| [What they do] | [Daily/Weekly/etc.] | (N/M participants) | +| [What they do] | [Frequency] | (N/M participants) | + +## Key Quotes + +> "[Representative quote]" +> -- user-001, [context] + +> "[Representative quote]" +> -- user-003, [context] + +[Cap at 5-7 quotes. Additional quotes in source interviews.] + +## Opportunities + +| # | Opportunity | Evidence Strength | Participants | Key Quote | +|---|-----------|------------------|-------------|-----------| +| 1 | Users need a way to [outcome] | Strong / Medium / Weak | user-001, user-003 | "[Quote]" | +| 2 | Users need a way to [outcome] | Strong / Medium / Weak | user-005 | "[Quote]" | + +## Divergences + +_No divergences identified yet._ + +[Or, when contradictions exist:] + +| Finding | Majority View | Minority View | Split | +|---------|--------------|---------------|-------| +| [Topic] | [View] (N/M) | [Contradicting view] (N/M) | N:N | + +## Evidence + +| Participant | Research Plan | Date | Focus | +|------------|--------------|------|-------| +| user-001 | [plan-slug] | YYYY-MM-DD | [Interview focus] | +| user-003 | [plan-slug] | YYYY-MM-DD | [Interview focus] | + +## Human Review Checklist + +- [ ] Goals and frustrations grounded in interview evidence +- [ ] Behavior counts accurate (absence not counted as negative) +- [ ] Quotes are exact (verified against source interviews) +- [ ] Opportunities framed as needs, not solutions +- [ ] Divergences section reflects actual contradictions +- [ ] Confidence level matches interview count threshold +``` + +## Examples + +**Example persona creation (from single interview):** + +Interview frontmatter: `role: Marketing Manager`, `company_type: B2B SaaS` + +Suggested persona name: "The Data-Driven Manager" +Confidence: low (1 interview) +All behaviors listed as (1/1 participants) + +**Example merge scenario:** + +Existing persona: "The Data-Driven Manager" (2 interviews, medium confidence) +New interview: `role: Marketing Manager`, `company_type: B2B SaaS` + +Match type: Exact match +Confirmation prompt shows: +- "The Data-Driven Manager" -- 2 interviews, medium confidence +- Key characteristics: morning dashboard routine, exports data weekly, manages team of 5 +- New interview: Marketing Manager at B2B SaaS, focus: reporting workflows + +After merge: interview_count: 3, confidence: medium, version: 3 + +**Example contradiction handling:** + +Existing finding: "Checks dashboard first thing in the morning" (2/2 participants) +New interview: Participant checks dashboard after standup, not first thing + +Result in Divergences table: + +| Finding | Majority View | Minority View | Split | +|---------|--------------|---------------|-------| +| Morning dashboard check | Check first thing (2/3) | Check after standup (1/3) | 2:1 | + +Behavior table updated: "Checks dashboard in the morning" (3/3 participants) -- all check it, timing differs. Divergence captures the timing disagreement. + +## Privacy Note + +Personas use anonymized participant IDs. Do not include real names or identifying details. The persona archetype name should be descriptive of the role, not the individual. diff --git a/plugins/compound-engineering/skills/research-plan/SKILL.md b/plugins/compound-engineering/skills/research-plan/SKILL.md new file mode 100644 index 00000000..2d4551ce --- /dev/null +++ b/plugins/compound-engineering/skills/research-plan/SKILL.md @@ -0,0 +1,223 @@ +--- +name: research-plan +description: "Create structured research plans with outcome-focused objectives, discussion guides, and screener questions. Use when planning user interviews, customer research, or discovery work." +--- + +# Research Plan + +**Note: The current year is 2026.** + +Create structured research plans grounded in Teresa Torres' Continuous Discovery Habits and Rob Fitzpatrick's Mom Test methodology. Plans focus on outcomes (not outputs), story-based interviewing, and past behavior over future speculation. + +**Reference:** [discovery-playbook.md](./references/discovery-playbook.md) -- Continuous Product Discovery Playbook with detailed methodology. + +## Quick Start + +1. Ask the user for the research objective (what outcome or decision this research will inform) +2. Identify target participants and screener criteria +3. Generate a research plan at `docs/research/plans/YYYY-MM-DD--research-plan.md` + +## Instructions + +### Step 1: Define the Research Objective + +Ask the user what outcome this research will inform. Reframe feature-level requests into outcome-level objectives. + +**Reframing examples:** +- "We want to add a dashboard" → "Understand how users monitor their key metrics and where current tools fall short" +- "Users want export to PDF" → "Understand the end-to-end workflow when users share data with stakeholders" + +Identify 2-4 hypotheses to test. Frame hypotheses as falsifiable statements about user behavior: +- "Users check their dashboard first thing in the morning" +- "Export is primarily used for sharing with non-users" + +### Step 2: Define the "Three Most Important Things to Learn" + +Distill the research objective into exactly three questions. These anchor every interview: +1. What is the current behavior? (past actions, not future intent) +2. What pain points exist in the current workflow? +3. What outcomes matter most to participants? + +### Step 3: Identify Participant Criteria + +Define who to interview: +- Role or job function +- Company type or industry +- Specific behaviors or usage patterns that qualify them +- Exclusion criteria (who should NOT be interviewed) + +Write 3-5 screener questions that filter for the right participants. Screeners should identify actual behavior, not self-reported preferences: +- "How many times did you export data last month?" (concrete, verifiable) +- NOT "Do you find exporting useful?" (opinion, not behavior) + +### Step 4: Create the Discussion Guide + +Build a story-based discussion guide following these principles: + +**Opening (2-3 minutes):** +- Establish rapport +- Explain the format: "Tell me about the last time you..." +- No pitching, no leading questions + +**Story Elicitation (15-20 minutes):** +- Start with a specific recent experience: "Walk me through the last time you [relevant activity]" +- Follow the story arc: trigger → actions → obstacles → outcome +- Drill into specifics with Mom Test questions: + - "What happened next?" + - "How did you handle that?" + - "What did you do instead?" (for workarounds) + - "Can you show me?" + +**Depth Probes (5-10 minutes):** +- Explore motivations: "Why was that important?" +- Surface latent needs: "What would change if that were easier?" +- Validate hypotheses with past behavior: "Has that happened before?" + +**Closing (2-3 minutes):** +- "Is there anything else about [topic] that I should have asked about?" +- Ask for referrals if recruiting more participants + +**Mom Test Rules (apply throughout):** +- Ask about past behavior, never future intent +- Ask about specifics, not generalizations +- Listen for emotional signals (frustration, excitement, resignation) +- Never pitch or describe a solution during the interview +- Compliments and hypothetical commitments are not data + +### Step 5: Set Sample Size and Schedule + +Recommend a sample size based on research goals: +- **Exploratory research** (understanding problem space): 5-8 participants +- **Evaluative research** (testing specific hypothesis): 3-5 participants +- **Continuous discovery** (ongoing learning): 1-2 per week + +### Step 6: Write the Plan + +Generate the research plan file at `docs/research/plans/YYYY-MM-DD--research-plan.md`. + +Ensure the `docs/research/plans/` directory exists before writing. + +## Output Template + +```markdown +--- +title: "[Research objective - short descriptive title]" +date: YYYY-MM-DD +status: planned +outcome: "[The outcome or decision this research informs]" +hypotheses: + - "[Hypothesis 1 - falsifiable statement about user behavior]" + - "[Hypothesis 2]" +participant_criteria: "[Role/behavior/company type criteria]" +sample_size: N +interviews_completed: 0 +--- + +# [Research Plan Title] + +## Objective + +[1-2 paragraphs describing the research outcome, why it matters, and what decisions it will inform] + +## Three Most Important Things to Learn + +1. [Question about current behavior] +2. [Question about pain points] +3. [Question about desired outcomes] + +## Hypotheses + +| # | Hypothesis | Status | +|---|-----------|--------| +| 1 | [Falsifiable statement] | UNTESTED | +| 2 | [Falsifiable statement] | UNTESTED | + +## Participant Criteria + +**Include:** +- [Criterion 1 - based on behavior] +- [Criterion 2] + +**Exclude:** +- [Exclusion 1] + +### Screener Questions + +1. [Behavior-based screener question] +2. [Behavior-based screener question] +3. [Behavior-based screener question] + +## Discussion Guide + +### Opening (2-3 min) + +- Introduce yourself and the purpose (learning, not selling) +- "I'd love to hear about your experience with [topic]. There are no wrong answers." + +### Story Elicitation (15-20 min) + +**Primary story prompt:** +> "Walk me through the last time you [relevant activity]." + +**Follow-up probes:** +- "What happened next?" +- "How did you handle that?" +- "What were you trying to accomplish?" +- "What made that difficult?" +- "What did you do instead?" + +### Depth Probes (5-10 min) + +- [Hypothesis-specific probe 1] +- [Hypothesis-specific probe 2] +- "Why was that important to you?" +- "Has that happened before? How often?" + +### Closing (2-3 min) + +- "Is there anything about [topic] I should have asked?" +- "Who else should I talk to about this?" + +## Post-Interview Checklist + +- [ ] Write interview snapshot within 24 hours (run `/workflows:research process`) +- [ ] Note top 3 surprises from this interview +- [ ] Update hypothesis status in this plan +- [ ] Identify follow-up questions for next interview +- [ ] Add new screener criteria if participant fit was imperfect + +## Schedule + +| # | Participant | Date | Status | +|---|-----------|------|--------| +| 1 | TBD | TBD | Scheduled | + +## Human Review Checklist + +- [ ] Objective is outcome-focused (not feature-focused) +- [ ] Hypotheses are falsifiable statements about behavior +- [ ] Screener questions ask about past behavior, not opinions +- [ ] Discussion guide follows story-based structure +- [ ] No leading questions or solution pitching in guide +- [ ] Sample size appropriate for research type +``` + +## Examples + +**Example objective reframing:** + +Input: "We need research for our new reporting feature" +Output objective: "Understand how teams currently create, share, and act on data reports, and where the workflow breaks down" + +**Example screener (good vs. bad):** + +| Quality | Question | +|---------|----------| +| Good | "How many reports did you create last month?" | +| Good | "Walk me through what you did after your last monthly review meeting." | +| Bad | "Do you think reporting is important?" | +| Bad | "Would you use a better reporting tool?" | + +## Privacy Note + +Consider adding `docs/research/transcripts/` to `.gitignore` if transcripts contain personally identifiable information. Research plans and processed insights (with anonymized participant IDs) are generally safe to commit. diff --git a/plugins/compound-engineering/skills/research-plan/references/discovery-playbook.md b/plugins/compound-engineering/skills/research-plan/references/discovery-playbook.md new file mode 100644 index 00000000..ca626bc5 --- /dev/null +++ b/plugins/compound-engineering/skills/research-plan/references/discovery-playbook.md @@ -0,0 +1,414 @@ +# Continuous Product Discovery Playbook +## A Best-Practices Guide for Product Managers & UX Researchers + +*Structuring Interviews, Extracting Insights from Transcripts, and Building a Sustainable Discovery System* + +--- + +## 1. Foundational Principles + +### 1.1 What Is Continuous Discovery? + +Continuous discovery is an approach where product teams maintain **at minimum, weekly touchpoints with customers**, conducting small research activities in pursuit of a desired product outcome (Teresa Torres, *Continuous Discovery Habits*). It replaces the outdated "big-bang research phase" with a persistent feedback loop that runs alongside delivery. + +**Core tenets:** +- **Outcome-focused, not output-focused.** Every discovery activity ties back to a measurable outcome (e.g., reduce churn, increase activation), not a feature request. +- **Weekly cadence.** Small, frequent interactions compound into deep user intuition over time. +- **Cross-functional ownership.** Discovery is co-owned by the **product trio** — a Product Manager, a Designer/UX Researcher, and an Engineer — who participate together in interviews and synthesis. +- **Lightweight and sustainable.** Discovery should not require elaborate study designs every week. Adapt methods to fit the time available. + +### 1.2 Why It Matters + +- **Healthier backlog:** Prioritization is grounded in real user evidence, not opinions or loudest-voice requests. +- **Lower cost of learning:** You discover problems with rough sketches and conversations, not after building and shipping. +- **Less reactive culture:** Teams spot opportunities before they become urgent escalations. +- **Compounding product judgment:** Persistent exposure to customers builds stronger intuition across the entire team. + +--- + +## 2. Setting Up a Discovery System + +### 2.1 Start With a Clear Outcome + +Before touching an interview guide, align your product trio on: +- **What behavior are we trying to change or improve?** +- **How does this tie into our OKRs / North Star metric?** +- **What do we need to learn to make a better decision?** + +Ground discovery in an outcome, not a feature. This prevents the trap of running interviews to validate a solution you've already committed to. + +### 2.2 Assemble the Product Trio + +| Role | Discovery Responsibility | +|---|---| +| **Product Manager** | Defines the outcome, prioritizes opportunities, owns the Opportunity Solution Tree | +| **UX Researcher / Designer** | Designs interview guides, moderates sessions, leads synthesis | +| **Engineer** | Assesses feasibility, participates in interviews (builds empathy for constraints and possibilities) | + +All three should attend interviews together whenever possible. Shared exposure eliminates the "telephone game" that happens when one person interviews and then reports findings to others. + +### 2.3 Automate Recruiting + +Recruiting is the #1 reason continuous interviewing fails. If scheduling is manual, the habit dies within weeks. Automate it so that interviews appear on your calendar every week without effort. + +**Proven recruiting channels:** + +| Channel | Best For | How It Works | +|---|---|---| +| **In-app intercepts** (e.g., Ethnio, Orbital) | Consumer & SaaS products | A pop-up screener appears inside the product; qualifying users schedule a call | +| **Customer support triggers** | Enterprise / B2B | Support agents flag specific scenarios and route users to the product team | +| **Insider connections** | Enterprise with named accounts | CSMs or account managers introduce product team to specific contacts | +| **Email campaigns** | Broad base | Targeted email to specific segments offering an incentive for 30 min of time | +| **Paid recruiting panels** | Hard-to-reach users | Services like UserInterviews, Respondent, or Prolific | + +**Key automation elements:** +- **Targeting:** Recruit the *right* users at the *right* time (e.g., users who completed onboarding 2+ weeks ago). +- **Screener questions:** Qualify in/out based on criteria relevant to your current outcome. +- **Automated reminders:** Email + SMS reminders reduce no-shows. +- **Self-scheduling:** Let participants pick from available calendar slots (Calendly, SavvyCal, etc.). + +--- + +## 3. Structuring Discovery Interviews + +### 3.1 Research Questions vs. Interview Questions + +A critical distinction (from Teresa Torres): +- **Research questions** = what you want to *learn* (e.g., "How often do users watch Netflix?"). +- **Interview questions** = what you actually *ask* (e.g., "Tell me about the last time you watched Netflix."). + +Research questions often make terrible interview questions. They encourage short, speculative, System 1 answers. Transform your research questions into **story-based prompts** that ground the participant in specific past behavior. + +### 3.2 The Mom Test (Rob Fitzpatrick) + +Three rules to ensure you get truthful, useful data — even from people who want to be polite: + +1. **Talk about their life instead of your idea.** Don't pitch; explore their reality. +2. **Ask about specifics in the past instead of generics or opinions about the future.** "Tell me about the last time…" beats "Would you ever…?" +3. **Talk less and listen more.** Your job is to extract signal, not to fill silence. + +**Deflect bad data:** +- **Compliments** ("That sounds really cool!") → Redirect: "Thanks — but tell me more about how you handle this today." +- **Fluff / generalities** ("I usually…" / "I always…") → Anchor: "When did that last happen? Walk me through it." +- **Hypothetical promises** ("I would definitely pay for that") → Dig: "What have you tried so far to solve this?" + +**Pre-interview discipline:** Before every conversation, write down the **three most important things you need to learn**. This keeps interviews focused and prevents aimless chatting. + +### 3.3 Story-Based Interviewing (Teresa Torres) + +The most reliable method for uncovering goals, context, and unmet needs. Instead of asking about general experiences, ask for **specific stories about past behavior**. + +**Why stories work:** +- They activate **System 2 thinking** (deliberate recall), producing more accurate answers than fast System 1 generalizations. +- They surface **context** — when, where, why, what device, what mood, who else was involved. +- They reveal **needs, pain points, and desires** (collectively: **opportunities**) that the participant may not even be consciously aware of. + +**The core prompt structure:** + +> "Tell me about the last time you [did the relevant activity]." +> "Tell me about a specific time when [relevant scenario]." + +**Interview flow:** + +| Phase | Duration | Purpose | Techniques | +|---|---|---|---| +| **Warm-up** | 2–3 min | Build rapport, set expectations | Easy personal questions; explain the purpose; reassure there are no right/wrong answers | +| **Story collection** | 15–20 min | Collect 1–2 specific stories about past behavior | "Tell me about the last time…"; follow up with "What happened next?"; gently redirect generalizations back to the specific instance | +| **Deepening** | 5–8 min | Explore pain points, workarounds, emotional context | "Tell me more about that"; "Why was that important?"; "How did you feel at that point?"; "What did you do next?" | +| **Wrap-up** | 2–3 min | Catch anything missed; close gracefully | "Is there anything else I should have asked?"; "Who else should I talk to?" | + +**Active listening techniques:** +- **Echoing:** Repeat the participant's last few words as a question to prompt elaboration. +- **Mirroring:** Match their body language and tone to build trust. +- **Comfortable silence:** Don't rush to fill pauses — participants often volunteer their best insights after a beat of silence. +- **Redirect generalizations:** When participants drift into "I usually…" or "I tend to…", gently guide back: "Can you think of a specific time that happened?" + +### 3.4 Question Bank: Good vs. Bad Questions + +| ❌ Avoid (Speculative / Leading / Closed) | ✅ Use Instead (Story-Based / Open-Ended) | +|---|---| +| "Would you use a feature that does X?" | "Tell me about the last time you tried to accomplish [goal]. What happened?" | +| "Do you like our product?" | "Walk me through the last time you used [product]. Start from the beginning." | +| "How often do you do X?" | "Tell me about the most recent time you did X. When was it? What was happening?" | +| "What's your biggest pain point?" | "Tell me about a time when [relevant task] was really frustrating. What happened?" | +| "What would your dream product do?" | "How are you solving this problem today? What have you tried?" | +| "Would you pay $X for Y?" | "Where does the money come from for tools like this? What's the buying process?" | +| "Do you think having the button on the left makes you less likely to click?" | "Walk me through what you did on this page. Was it easy to complete your task? Why or why not?" | + +### 3.5 Preparing the Discussion Guide + +A discussion guide is **flexible, not a rigid script**. It ensures you cover key topics while leaving room to follow interesting threads. + +**Structure:** +1. **Research goal** (1–2 sentences): What outcome are we learning about? +2. **Screening criteria:** Who qualifies for this interview? +3. **Warm-up questions** (2–3): Easy openers to build rapport. +4. **Story prompts** (2–3): Core story-based questions tied to your research goal. +5. **Follow-up / probing questions** (5–8): Nested under each story prompt — use as needed. +6. **Wrap-up questions** (1–2): "Anything else?" and referral questions. +7. **Debrief checklist:** Reminders for what to capture in your interview snapshot immediately after. + +--- + +## 4. Synthesizing Interviews: The Interview Snapshot + +### 4.1 Why Immediate Synthesis Matters + +> "Synthesize each interview immediately after it ends. Capture your thoughts while they're fresh, rather than assuming you'll revisit the recording or notes later." — Teresa Torres + +Memory degrades rapidly. Schedule **15 minutes immediately after every interview** for synthesis. The product trio should do this together — co-creation builds shared understanding. + +### 4.2 The Interview Snapshot (Teresa Torres) + +A **one-page summary** that makes each interview memorable, actionable, and reference-able. The product trio collaborates to complete it in 15–20 minutes post-interview. + +**Seven components:** + +| Component | What to Capture | +|---|---| +| **1. Name & Photo** | Identify and remember the participant | +| **2. Quick Facts** | Key context: role, segment, tenure, relevant demographics | +| **3. Memorable Quote** | A single quote that captures the essence of the story — helps trigger recall later | +| **4. Experience Map** | A simple visual timeline of the story they told (beginning → middle → end) with key moments marked | +| **5. Opportunities** | Unmet needs, pain points, and desires that surfaced during the story | +| **6. Insights** | Interesting learnings that aren't yet opportunities but may become relevant later | +| **7. Follow-up Items** | Open questions, things to verify, people to talk to next | + +**Templates available in:** Miro (Product Talk template), FigJam, Google Slides, PowerPoint, Keynote. + +**Key principle:** The snapshot is **synthesis, not transcription**. You are distilling meaning, not capturing every word. + +--- + +## 5. Extracting Insights from Transcripts + +### 5.1 Transcription First + +Before analysis, convert recordings to searchable text. This is the foundation for all downstream work. + +| Method | Best For | Considerations | +|---|---|---| +| **Automated transcription** (Otter.ai, Rev, Dovetail, Condens) | Speed; most use cases | Review critical sections manually — AI struggles with names, jargon, crosstalk | +| **Human transcription** | High-stakes research; heavy accents/jargon | More accurate but slower and more expensive | +| **Hybrid** | Enterprise research | Auto-transcribe first, then human-proofread key sections | + +**Essential metadata per session:** +- Session ID (stable, unique code) +- Date and type (interview, usability test, support call) +- Participant profile fields (role, segment, plan tier, region) +- Moderator/researcher and study name +- Consent/usage notes +- Links to recording and transcript files + +### 5.2 Highlighting: Capture Atomic Evidence + +Before tagging or theming, **highlight** the meaningful moments in each transcript. Each highlight should be an **atomic evidence unit** — a single observation, quote, or behavior that can stand alone. + +**What to highlight:** +- Direct quotes expressing needs, pain points, or desires +- Descriptions of behavior (what the participant actually did) +- Emotional reactions (frustration, surprise, delight) +- Workarounds and hacks (signals of unmet needs) +- Contradictions between stated preferences and actual behavior + +**Principle:** Highlight first, tag second, synthesize third. Don't jump to themes too early. + +### 5.3 Coding / Tagging + +Coding (or tagging) is the process of labeling highlights to enable pattern discovery across multiple interviews. + +**Two approaches:** + +| Approach | Description | When to Use | +|---|---|---| +| **Deductive (top-down)** | Define codes *before* reviewing data, based on research questions and hypotheses | When you have specific questions to answer; faster for time-constrained projects | +| **Inductive (bottom-up)** | Let codes emerge *from* the data as you review | When exploring new territory; prevents premature categorization | +| **Hybrid** | Start with a small set of deductive codes, then add inductive codes as new themes emerge | Most common in practice; balances speed and openness | + +**Practical tagging taxonomy:** + +| Tag Category | Examples | Purpose | +|---|---|---| +| **Descriptive** | Location, device, role, task, feature area | Organize by context | +| **Emotional** | Frustration, delight, confusion, surprise | Build empathy; identify emotional peaks | +| **Behavioral** | Workaround, abandonment, comparison shopping, habit | Surface actual behavior patterns | +| **Need/Pain Point** | Unmet need, pain point, desire, blocker | Feed directly into opportunities | +| **Evaluative** | Like, dislike, strong preference, indifference | Capture sentiment toward specific elements | + +**Best practices for a shared codebook:** +- Keep the tag set small (15–25 tags) and expand only when needed. +- Write a 1-sentence definition for each tag so teammates apply them consistently. +- Review and consolidate tags periodically — merge synonyms, retire unused tags. +- Use a shared tool (Dovetail, Condens, Notion, or even a spreadsheet) so the whole team sees the same taxonomy. + +### 5.4 Affinity Mapping & Thematic Analysis + +Once you've highlighted and tagged across multiple interviews, affinity mapping helps you see the patterns. + +**Step-by-step process:** + +1. **Gather all highlights** — Pull tagged quotes, observations, and notes from all interviews onto a shared surface (digital whiteboard, Miro, FigJam, or physical sticky notes). +2. **Group by similarity** — Move items that feel related near each other. Don't overthink categories yet — trust your intuition. +3. **Name the clusters** — Once groups form, give each a descriptive label that captures the theme (e.g., "Users distrust automated recommendations," "Onboarding feels overwhelming in week 1"). +4. **Look for hierarchy** — Some clusters may be sub-themes of larger themes. Nest them. +5. **Quantify (loosely)** — Note how many participants contributed to each theme and from which segments. This isn't statistical analysis — it's pattern recognition. +6. **Identify outliers** — Don't ignore insights that don't fit neatly. Outliers can signal emerging opportunities. +7. **Document** — Write a theme statement for each cluster, supported by 2–3 representative quotes with source references. + +**Watch out for bias:** +- **Confirmation bias:** Gravitating toward themes that confirm your hypotheses. +- **Recency bias:** Over-weighting the most recent interviews. +- **Loudness bias:** Giving more weight to articulate or emotionally expressive participants. + +Affinity mapping in a group (the product trio + stakeholders) helps counter individual bias through diverse perspectives. + +### 5.5 Atomic Research Nuggets + +For teams running continuous discovery over months/years, the **atomic research** approach (developed by Tomer Sharon and Daniel Pidcock) prevents insights from getting buried in reports. + +**What is a nugget?** +A nugget is the smallest indivisible unit of research insight: +- **Observation:** A single finding or fact (e.g., "3 of 5 users abandoned the wizard at step 3") +- **Evidence:** The source data that supports it (quote, timestamp, video clip) +- **Tags:** Metadata for searchability (feature area, user segment, research study) + +**Why nuggets work:** +- They are **reusable** across projects — you don't re-run the same research because someone didn't read last year's report. +- They are **searchable** — stakeholders can self-serve insights from a research repository. +- They are **composable** — multiple nuggets combine into higher-level insights and themes. + +**Storage:** Use a research repository tool (Dovetail, Condens, EnjoyHQ, Notion) or a structured spreadsheet with consistent tagging. + +--- + +## 6. From Insights to Action: The Opportunity Solution Tree + +### 6.1 What Is an Opportunity Solution Tree (OST)? + +The Opportunity Solution Tree, popularized by Teresa Torres, is a visual framework that connects: + +``` +Outcome (metric) + └── Opportunities (needs, pain points, desires) + └── Solutions (ideas to address opportunities) + └── Experiments (tests to validate solutions) +``` + +It ensures every solution traces back to a real customer opportunity, which traces back to a measurable business outcome. + +### 6.2 How to Build an OST + +1. **Set the outcome** — Place your target metric at the top of the tree (e.g., "Increase weekly active users by 15%"). +2. **Create an experience map** — Have each member of the product trio draw what they believe the current customer experience looks like. Merge into a shared map. Gaps in the map guide your interviews. +3. **Map opportunities from interview snapshots** — Every 3–4 interviews, review your snapshots and pull out the opportunities (needs, pain points, desires). Place them on the tree under the relevant moment in the experience map. +4. **Structure the opportunity space** — Group and nest related opportunities. Parent opportunities are broad (e.g., "Users struggle to find relevant content"); child opportunities are more specific (e.g., "Search results don't account for past viewing history"). +5. **Select a target opportunity** — Compare and contrast opportunities. Choose one that is solvable, impactful, and aligned with your outcome. +6. **Generate solutions** — Brainstorm multiple solutions for the target opportunity (divergent thinking). Don't commit to the first idea. +7. **Design experiments** — For each promising solution, identify the riskiest assumption and design a small test to validate or invalidate it. +8. **Iterate** — As you learn, revise the tree. New interviews add new opportunities. Failed experiments redirect you to alternative solutions. + +### 6.3 Common Pitfalls + +- **Framing opportunities as solutions.** "We need a better search bar" is a solution. The opportunity is "Users can't find content relevant to their interests." Practice separating the two. +- **Overreacting to the latest interview.** The tree prevents this by providing a big-picture view. One interview = one data point. Update the tree after every 3–4 interviews, not after every single one. +- **Skipping opportunity mapping.** Teams that jump from interview to solution miss the chance to compare opportunities strategically. +- **Setting the wrong outcome.** If your outcome isn't connected to business strategy, the whole tree drifts. Re-validate your outcome quarterly. + +--- + +## 7. Tools for Continuous Discovery + +| Category | Tools | Purpose | +|---|---|---| +| **Recruiting & Scheduling** | Ethnio, Orbital, Great Question, Calendly, UserInterviews | Automate participant recruitment and scheduling | +| **Video & Transcription** | Zoom, Grain, Otter.ai, Rev, Descript | Record interviews and generate transcripts | +| **Research Repository & Analysis** | Dovetail, Condens, EnjoyHQ, Notion, Airtable | Store, tag, search, and synthesize research data | +| **Synthesis & Mapping** | Miro, FigJam, Figjam, MURAL | Interview snapshots, affinity maps, experience maps, OSTs | +| **Opportunity Solution Trees** | Miro (Product Talk templates), Vistaly, ProductBoard | Visualize and manage the opportunity space | +| **AI-Assisted Analysis** | Dovetail AI, Condens AI, ChatGPT, Claude | Auto-transcription, auto-tagging, summarization (always human-validate) | + +**A note on AI tools:** AI can speed up transcription, suggest tags, and draft theme summaries. However, **do not rely on AI exclusively for synthesis** (per Teresa Torres). The act of personally reviewing conversations and identifying patterns is where deep understanding forms. Use AI to surface things you might overlook, not to replace your thinking. + +--- + +## 8. Building the Habit: Making Discovery Stick + +### 8.1 Weekly Cadence Template + +| Day | Activity | Time | +|---|---|---| +| **Monday** | Review upcoming interview schedule (auto-populated) | 5 min | +| **Tuesday** | Conduct interview #1; complete interview snapshot | 45–60 min | +| **Thursday** | Conduct interview #2; complete interview snapshot | 45–60 min | +| **Friday** | Cross-interview synthesis: update OST, review patterns | 30–45 min | + +This is approximately **2–3 hours per week** — roughly 5-7% of a trio's working hours. + +### 8.2 Protect Discovery Time + +- **Treat discovery like sprint planning** — it's not optional; it's on the calendar. +- **Batch interviews** — Don't spread them across random slots. Dedicated blocks reduce context-switching. +- **Rotate moderation** — Each trio member should take turns leading interviews to build shared capability. +- **Share snapshots visibly** — Post them in a team channel (Slack, Teams) or a shared Miro board so stakeholders stay informed without attending every session. + +### 8.3 Scaling Across Teams + +- **Create a shared codebook** — Standard tags and definitions across teams enable cross-team insight discovery. +- **Maintain a centralized research repository** — All snapshots, nuggets, and themes live in one searchable place. +- **Run periodic "insight jams"** — Monthly sessions where multiple trios review each other's OSTs and cross-pollinate opportunities. +- **Train PMs and designers on story-based interviewing** — The skill gap is the bottleneck, not the process. + +--- + +## 9. Quick-Reference Checklists + +### Pre-Interview Checklist +- [ ] Outcome defined and agreed upon by the product trio +- [ ] Discussion guide prepared (2–3 story prompts, follow-up questions) +- [ ] Participant recruited and confirmed (screener passed) +- [ ] Recording tool set up and tested +- [ ] Trio roles assigned (moderator, note-taker, observer) +- [ ] Three most important learning goals written down (The Mom Test) + +### During-Interview Checklist +- [ ] Warm-up complete; participant is comfortable +- [ ] Collecting specific stories about past behavior (not opinions about the future) +- [ ] Redirecting generalizations back to specifics +- [ ] Using active listening (echoing, silence, "tell me more") +- [ ] Not pitching solutions or leading the witness +- [ ] Capturing timestamps of key moments for later reference + +### Post-Interview Checklist +- [ ] Interview snapshot completed within 15–20 minutes +- [ ] Opportunities and insights documented +- [ ] Experience map drawn for the story collected +- [ ] Snapshot shared with the team +- [ ] Follow-up items logged +- [ ] Opportunities added to the Opportunity Solution Tree (after every 3–4 interviews) + +### Transcript Analysis Checklist +- [ ] Transcript reviewed and cleaned (names, jargon corrected) +- [ ] Key moments highlighted as atomic evidence units +- [ ] Highlights tagged using shared codebook +- [ ] Themes identified through affinity mapping +- [ ] Themes documented with supporting quotes and source references +- [ ] Findings connected to existing opportunities on the OST +- [ ] Insights stored in research repository for future reference + +--- + +## 10. Recommended Reading & Sources + +| Resource | Author | Key Contribution | +|---|---|---| +| *Continuous Discovery Habits* | Teresa Torres | The definitive framework for weekly customer touchpoints, interview snapshots, and Opportunity Solution Trees | +| *The Mom Test* | Rob Fitzpatrick | Rules for asking questions that produce truthful, useful answers | +| Product Talk Blog (producttalk.org) | Teresa Torres | Story-based interviewing, opportunity mapping, and OST deep dives | +| NN/g User Interviews 101 | Nielsen Norman Group | Foundational interviewing methodology for UX researchers | +| *Thinking, Fast and Slow* | Daniel Kahneman | Understanding System 1 vs. System 2 thinking and why story-based questions produce better data | +| Atomic Research | Tomer Sharon & Daniel Pidcock | Breaking research into reusable, searchable nuggets | +| Dovetail/Condens Workflows | Various | Practical transcript-to-theme synthesis workflows | + +--- + +*This playbook is a living document. Update it as your team's discovery practice matures. The goal is not perfection — it's a sustainable habit of learning from your customers every single week.* diff --git a/plugins/compound-engineering/skills/transcript-insights/SKILL.md b/plugins/compound-engineering/skills/transcript-insights/SKILL.md new file mode 100644 index 00000000..ccf4d665 --- /dev/null +++ b/plugins/compound-engineering/skills/transcript-insights/SKILL.md @@ -0,0 +1,298 @@ +--- +name: transcript-insights +description: "Process interview transcripts into structured snapshots with tagged insights, experience maps, and opportunity identification. Use when a transcript exists in docs/research/transcripts/ or when pasting interview content." +--- + +# Transcript Insights + +**Note: The current year is 2026.** + +Process raw interview transcripts into structured interview snapshots following Teresa Torres' one-page interview snapshot format. Extract atomic insights, map experience timelines, identify opportunities in Opportunity Solution Tree language, and track hypothesis status. + +**Reference:** [discovery-playbook.md](../research-plan/references/discovery-playbook.md) -- Continuous Product Discovery Playbook with detailed methodology. + +## Quick Start + +1. Accept a transcript file path or pasted content +2. Link to a research plan (or mark as ad-hoc) +3. Generate an interview snapshot at `docs/research/interviews/YYYY-MM-DD-participant-NNN.md` + +## Instructions + +### Step 1: Accept Input + +Check `$ARGUMENTS` for a file path. If empty, prompt: +- "Provide the path to a transcript in `docs/research/transcripts/`, or paste the transcript content directly." + +If a file path is given, read the transcript. If the file does not exist, report the error and stop. + +If content is pasted directly, proceed with that content (no file reference in output frontmatter). + +### Step 2: Link to Research Plan + +Check for files in `docs/research/plans/`. + +**If no plans exist:** +Set `research_plan: ad-hoc` in frontmatter and proceed to Step 3. + +**If plans exist:** +List existing research plans by reading frontmatter from files in `docs/research/plans/`: +- Show title, date, and status for each plan +- Most recent first, cap at 7 entries +- Include "Ad-hoc / no plan" as the final option + +Use AskUserQuestion to ask which plan this transcript belongs to. Store the plan slug (filename without date prefix and extension) in the output frontmatter. + +If "Ad-hoc" is selected, set `research_plan: ad-hoc` in frontmatter. + +### Step 3: Gather Metadata + +Ask the user for participant metadata (use AskUserQuestion where appropriate): +- **Participant ID**: Suggest format `user-NNN` based on existing interviews +- **Role**: Job title or function (e.g., "Marketing Manager") +- **Company type**: Industry or company category (e.g., "B2B SaaS") +- **Interview focus**: Brief topic description +- **Duration**: Approximate length in minutes + +Check existing interviews in `docs/research/interviews/` for the next available participant number. + +### Step 4: Process the Transcript + +Read the full transcript and extract the following components: + +#### 4a: Interview Summary + +Write a 3-5 sentence summary capturing the key narrative arc. Focus on what the participant actually did (past behavior), not what they said they would do. + +#### 4b: Experience Map + +Create a timeline of the participant's experience as described in the interview. Follow the story arc: + +``` +Trigger → Context → Actions → Obstacles → Workarounds → Outcome +``` + +For each step, note: +- What happened (factual) +- How the participant felt (emotional signals) +- What tools or processes were involved + +#### 4c: Atomic Insights + +Extract individual insights from the transcript. Each insight must be: +- **Atomic**: One observation per insight +- **Evidence-based**: Tied to a specific quote or described behavior +- **Tagged**: With exactly ONE type tag and 1-3 topic tags + +Quote every insight. Use the participant's exact words. Do not paraphrase, composite, or fabricate quotes. If the insight comes from observed behavior rather than a direct quote, note it as `[Observed behavior]` instead. + +#### 4d: Opportunities + +Frame opportunities in Opportunity Solution Tree language: +- Opportunities are unmet needs, pain points, or desires -- NOT solutions +- "Users need a way to [outcome]" not "Build a [feature]" +- Rate evidence strength based on how directly the participant expressed the need + +#### 4e: Hypothesis Tracking + +If linked to a research plan, evaluate each hypothesis from the plan: +- **SUPPORTED**: This interview provides evidence supporting the hypothesis +- **CHALLENGED**: This interview provides evidence contradicting the hypothesis +- **MIXED**: Evidence is ambiguous or partially supports +- **NEW**: A new hypothesis emerged from this interview (not in original plan) +- **NO DATA**: This interview did not address this hypothesis + +Provide the specific evidence (quote or behavior) for each status assignment. + +#### 4f: Behavioral Observations + +Note non-verbal or contextual observations: +- Tools or screens the participant mentioned or demonstrated +- Emotional reactions (frustration, excitement, confusion) +- Workarounds or hacks they described +- Frequency indicators ("every day", "once a month", "whenever I need to") + +### Step 5: Write the Interview Snapshot + +Generate the file at `docs/research/interviews/YYYY-MM-DD-participant-NNN.md`. + +Ensure the `docs/research/interviews/` directory exists before writing. + +## Tag Taxonomy + +### Type Tags (Fixed Set) + +Assign exactly ONE type tag per insight: + +| Tag | Use When | +|-----|----------| +| `pain-point` | Participant describes frustration, difficulty, or failure | +| `need` | Participant expresses a requirement or necessity | +| `desire` | Participant wishes for something beyond basic needs | +| `behavior` | Participant describes what they actually do (neutral observation) | +| `workaround` | Participant describes a hack or alternative to compensate for a gap | +| `motivation` | Participant explains why something matters to them | + +### Topic Tags (Semi-Open) + +Assign 1-3 topic tags per insight: +- Lowercase, hyphenated, singular (e.g., `dashboard`, `data-export`, `morning-workflow`) +- Before creating a new topic tag, check existing interviews for established tags +- Grep `docs/research/interviews/` for `tags:` lines to find existing tags +- Prefer existing tags over creating new synonyms + +## Output Template + +```markdown +--- +participant_id: user-NNN +role: "[Job title or function]" +company_type: "[Industry or company category]" +date: YYYY-MM-DD +research_plan: "[plan-slug or ad-hoc]" +source_transcript: "[transcript-filename.md]" +focus: "[Brief topic description]" +duration_minutes: NN +tags: [topic-tag-1, topic-tag-2, topic-tag-3] +--- + +# Interview Snapshot: [Participant ID] + +## Summary + +[3-5 sentence narrative summary focusing on past behavior and key story arc] + +## Experience Map + +``` +[Trigger] → [Context] → [Actions] → [Obstacles] → [Workarounds] → [Outcome] +``` + +| Step | What Happened | Feeling | Tools/Process | +|------|--------------|---------|---------------| +| Trigger | [Event that started the workflow] | [Emotional state] | [Tool/process] | +| Action 1 | [What they did] | [Emotional state] | [Tool/process] | +| Obstacle | [What blocked them] | [Emotional state] | - | +| Workaround | [How they got around it] | [Emotional state] | [Tool/process] | +| Outcome | [End result] | [Emotional state] | - | + +## Insights + +### Pain Points + +> "[Exact quote from transcript]" +- **Type:** pain-point +- **Topics:** [tag-1], [tag-2] +- **Context:** [Brief context for the quote] + +### Needs + +> "[Exact quote from transcript]" +- **Type:** need +- **Topics:** [tag-1] +- **Context:** [Brief context] + +### Behaviors + +> "[Exact quote or [Observed behavior] description]" +- **Type:** behavior +- **Topics:** [tag-1], [tag-2] +- **Context:** [Brief context] + +### Workarounds + +> "[Exact quote from transcript]" +- **Type:** workaround +- **Topics:** [tag-1] +- **Context:** [Brief context] + +### Desires + +> "[Exact quote from transcript]" +- **Type:** desire +- **Topics:** [tag-1] +- **Context:** [Brief context] + +### Motivations + +> "[Exact quote from transcript]" +- **Type:** motivation +- **Topics:** [tag-1] +- **Context:** [Brief context] + +## Opportunities + +Opportunities are unmet needs -- NOT solutions. + +| # | Opportunity | Evidence Strength | Quote | +|---|-----------|------------------|-------| +| 1 | Users need a way to [outcome] | Strong / Medium / Weak | "[Supporting quote]" | +| 2 | Users need a way to [outcome] | Strong / Medium / Weak | "[Supporting quote]" | + +**Evidence strength:** +- **Strong**: Participant explicitly described this need with emotional weight +- **Medium**: Participant mentioned this in passing or as part of a larger story +- **Weak**: Inferred from behavior or workaround, not directly stated + +## Hypothesis Tracking + +| # | Hypothesis | Status | Evidence | +|---|-----------|--------|----------| +| 1 | [From research plan] | SUPPORTED / CHALLENGED / MIXED / NEW / NO DATA | "[Quote or behavior]" | +| 2 | [From research plan] | SUPPORTED / CHALLENGED / MIXED / NEW / NO DATA | "[Quote or behavior]" | + +## Behavioral Observations + +- **Tools mentioned:** [List of tools, software, processes referenced] +- **Frequency indicators:** [How often activities occur] +- **Emotional signals:** [Notable reactions during interview] +- **Workaround patterns:** [Hacks or alternative approaches described] + +## Human Review Checklist + +- [ ] All quotes verified against source transcript +- [ ] Experience map accurately reflects story arc +- [ ] Opportunities reflect participant needs, not assumed solutions +- [ ] Tags accurate and consistent with existing taxonomy +- [ ] No insights fabricated or composited from multiple participants +``` + +## Examples + +**Example insight extraction:** + +Transcript excerpt: +> "Every morning I open three different tabs -- the dashboard, the Slack channel, and this spreadsheet I maintain. I basically copy numbers from the dashboard into my spreadsheet because the export never works right." + +Extracted insights: + +1. > "Every morning I open three different tabs -- the dashboard, the Slack channel, and this spreadsheet I maintain." + - **Type:** behavior + - **Topics:** morning-workflow, dashboard, multi-tool + - **Context:** Describing daily monitoring routine + +2. > "I basically copy numbers from the dashboard into my spreadsheet because the export never works right." + - **Type:** workaround + - **Topics:** data-export, dashboard + - **Context:** Manual data transfer to compensate for broken export + +Extracted opportunity: +- "Users need a reliable way to get dashboard data into their own tracking tools" (NOT "Build a better export button") + +**Example hypothesis tracking:** + +| Hypothesis | Status | Evidence | +|-----------|--------|----------| +| Users check dashboard first thing in the morning | SUPPORTED | "Every morning I open three different tabs -- the dashboard, the Slack channel, and this spreadsheet" | +| Export is primarily used for sharing with non-users | CHALLENGED | Export is used for personal tracking spreadsheet, not sharing | + +## Privacy Note + +Interview snapshots use anonymized participant IDs (user-001, user-002). Do not include real names, email addresses, or other identifying information in the snapshot output. When processing transcripts: + +- **Replace all real names** with anonymized IDs (e.g., "user-001") in quotes and context +- **Replace company names** with generic descriptors (e.g., "a regional health plan") unless the company is public knowledge and relevant to the insight +- **Strip identifying details** from the `source_transcript` frontmatter field -- use a descriptive slug, not the original filename if it contains names +- **Quotes must be exact** from the transcript, but with PII replaced inline (e.g., `"[user-001] said the export was broken"`) + +Transcripts in `docs/research/transcripts/` contain raw interview data with PII and MUST NOT be committed to public repositories. The `.gitignore` includes `docs/research/transcripts/*.md` by default.