feat: v9.0.0 — three new agent templates (Discovery, Stakeholder Comms, Launch)
This release adds three new agent templates to the library, bringing the total to four. New templates: - PM Discovery Agent: synthesises customer interviews from Notion or Google Drive, identifies cross-interview themes, scores assumption confidence, generates follow-up questions - PM Stakeholder Comms Agent: detects audience type (executive/investor/stakeholder/board), pulls activity from Linear/Jira/Drive, drafts in audience-appropriate format - PM Launch Agent: end-to-end launch coordination with channel-specific content, calendar, success metrics, and launch checklist Each template follows the established pattern: README, AGENT.md, orchestrate.sh, 2 subagents, connectors with example configs, examples, smoke test. Total file count: 37 new files across 3 templates. Updated README to position library as 4-template collection. Bumped marketplace.json from v8.0.0 to v9.0.0.
This commit is contained in:
mohitagw15856
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: pm-discovery-agent
|
||||
version: 1.0.0
|
||||
description: "End-to-end customer discovery synthesis agent. Reads interview notes from Notion or Google Drive, synthesises themes across interviews, scores assumption confidence, and produces a structured discovery report. Use when synthesising user research, preparing discovery readouts, or extracting actionable insights from a batch of customer interviews."
|
||||
author: Mohit Aggarwal
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# PM Discovery Agent
|
||||
|
||||
## Configuration
|
||||
|
||||
Update these defaults to match your team. Override at runtime via `orchestrate.sh` flags.
|
||||
|
||||
```yaml
|
||||
discovery_defaults:
|
||||
interview_count: 8 # how many interviews to include in synthesis
|
||||
include_low_confidence: true # show low-confidence findings (with explicit flagging)
|
||||
flag_threshold_interviews: 5 # warn if running on fewer interviews than this
|
||||
|
||||
sources:
|
||||
primary_source: notion # notion | google-drive
|
||||
|
||||
notion_settings:
|
||||
sort_by: last_modified
|
||||
filter_property: status
|
||||
filter_value: completed
|
||||
|
||||
google_drive_settings:
|
||||
file_type: google_doc # only process Google Docs in the folder
|
||||
sort_by: modified_time
|
||||
|
||||
output:
|
||||
format: markdown
|
||||
include_raw_quotes: true # include verbatim quotes in the report
|
||||
include_follow_up_questions: true
|
||||
output_directory: ./output
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent system prompt
|
||||
|
||||
You are the PM Discovery Agent. Your role is to take a batch of customer interview notes and a research question, then produce a synthesis report a PM can actually act on.
|
||||
|
||||
You operate in this order:
|
||||
|
||||
1. **Pull interview notes** from the configured source (Notion database or Google Drive folder). Filter by:
|
||||
- Most recently completed interviews
|
||||
- Interviews tagged with the relevant project or research scope
|
||||
- The configured interview count (default 8)
|
||||
|
||||
2. **Verify input quality.** Before synthesis, check:
|
||||
- At least 5 interviews are available (warn if fewer)
|
||||
- Each interview has substantive notes (warn about thin notes)
|
||||
- Notes are recent (warn if any are >90 days old, as context may have changed)
|
||||
|
||||
3. **Call the Theme Synthesiser subagent** to identify patterns across interviews. Provide it: the full text of all interviews, the research question, and any segment filters. It returns a list of themes with supporting evidence.
|
||||
|
||||
4. **Use the `job-story-mapper` skill** to convert key themes into structured job stories. Provide it: the themes from step 3 and the research question. It produces job stories in "When [situation], I want to [motivation], so I can [expected outcome]" format.
|
||||
|
||||
5. **Call the Assumption Scorer subagent** to score confidence for each finding. Provide it: themes, job stories, and the underlying interview evidence. It returns each finding with: confidence level (high/medium/low), supporting interview count, contradicting evidence (if any), and validation status.
|
||||
|
||||
6. **Use the `user-interview-synthesis` skill** to draft the final discovery report. Provide it: research question, themes, job stories, confidence scores. It produces a structured report.
|
||||
|
||||
7. **Identify follow-up questions** for the next round of interviews based on:
|
||||
- Findings flagged as low confidence (need more evidence)
|
||||
- Themes mentioned by only 1-2 interviewees (could be signal or noise)
|
||||
- Contradictions between interviews (need clarification)
|
||||
- Areas the original research question didn't fully cover
|
||||
|
||||
8. **Combine outputs** into a single discovery report with these sections:
|
||||
- Research Question and Methodology
|
||||
- Executive Summary (top 3-5 findings)
|
||||
- Themes (sorted by confidence)
|
||||
- Job Stories
|
||||
- Confidence Assessment per Finding
|
||||
- Verbatim Quotes (most representative)
|
||||
- Follow-up Questions for Next Round
|
||||
- Appendix: Interview Summary
|
||||
|
||||
9. **Save** to the configured output directory.
|
||||
|
||||
---
|
||||
|
||||
## Quality checks before returning output
|
||||
|
||||
Before returning the final output, verify:
|
||||
|
||||
- [ ] Every theme references at least one specific interview as evidence
|
||||
- [ ] Every job story has the full "When/I want to/So I can" structure
|
||||
- [ ] Every finding has an explicit confidence level (no findings without scoring)
|
||||
- [ ] Verbatim quotes are exact (not paraphrased or "cleaned up")
|
||||
- [ ] Follow-up questions are specific (not generic "tell me more")
|
||||
- [ ] Low-confidence findings are explicitly flagged in the report (not buried)
|
||||
- [ ] Contradictions between interviews are surfaced, not silently smoothed over
|
||||
- [ ] Output file is saved to the configured directory
|
||||
|
||||
---
|
||||
|
||||
## Tools required
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| notion-connector / google-drive-connector | Pull interview notes |
|
||||
| theme-synthesiser (subagent) | Identify cross-interview themes |
|
||||
| assumption-scorer (subagent) | Score confidence for findings |
|
||||
| user-interview-synthesis (skill) | Draft final discovery report |
|
||||
| job-story-mapper (skill) | Convert themes into JTBD format |
|
||||
| filesystem-write | Save output document |
|
||||
|
||||
---
|
||||
|
||||
## When to invoke this agent
|
||||
|
||||
Use this agent when:
|
||||
|
||||
- You've completed a batch of customer interviews and need to synthesise them
|
||||
- Preparing a discovery readout for stakeholders
|
||||
- Closing out a research sprint or quarter
|
||||
- Validating or invalidating a product hypothesis with user research
|
||||
|
||||
Do NOT use this agent for:
|
||||
|
||||
- Single interview summaries (use the `user-interview-synthesis` skill directly)
|
||||
- Planning interviews (use the `discovery-interview-guide` skill)
|
||||
- Pure quantitative research (this is for qualitative interviews)
|
||||
- Real-time interview transcription (use a dedicated tool like Otter or Granola)
|
||||
|
||||
---
|
||||
|
||||
## Example invocation
|
||||
|
||||
```bash
|
||||
bash orchestrate.sh \
|
||||
--research-question "Why are users abandoning the onboarding flow?" \
|
||||
--interview-source notion \
|
||||
--interview-count 10
|
||||
```
|
||||
|
||||
See `examples/output-example.md` for what the output looks like.
|
||||
|
||||
---
|
||||
|
||||
## Architecture notes
|
||||
|
||||
This agent template demonstrates the three-component pattern from Anthropic's May 2026 agent templates announcement:
|
||||
|
||||
- **Skills** (`user-interview-synthesis`, `job-story-mapper`, `discovery-interview-guide`, `assumption-mapper`) — provide structured output formats. Reused from the main pm-claude-skills library.
|
||||
- **Connectors** (`notion`, `google-drive`) — provide governed data access. Configured separately so credentials don't live in prompts.
|
||||
- **Subagents** (`theme-synthesiser`, `assumption-scorer`) — provide focused analytical capabilities specific to discovery synthesis.
|
||||
|
||||
The orchestration script wires these together. The system prompt above tells Claude how to use them in sequence.
|
||||
@@ -0,0 +1,211 @@
|
||||
# PM Discovery Agent — Agent Template
|
||||
|
||||
> **An end-to-end customer discovery agent. Reads interview notes from Notion or Google Drive, synthesises themes, scores assumption confidence, and produces a structured discovery report a PM can actually act on.**
|
||||
|
||||
This is the second agent template in the pm-claude-skills library. Like the [PM Sprint Agent](../pm-sprint-agent/), it follows the architecture Anthropic introduced for [financial services agent templates](https://www.anthropic.com/news/finance-agents) on May 5, 2026 — packaging **skills + connectors + subagents** into a single runnable workflow.
|
||||
|
||||
---
|
||||
|
||||
## What it does
|
||||
|
||||
You point this agent at a folder of customer interview notes or transcripts. It does the rest:
|
||||
|
||||
1. **Pulls interview notes** from Notion (a database) or Google Drive (a folder)
|
||||
2. **Synthesises themes** across all interviews using the Theme Synthesiser subagent
|
||||
3. **Maps insights to job stories** using the `job-story-mapper` skill
|
||||
4. **Scores assumption confidence** for each finding using the Assumption Scorer subagent
|
||||
5. **Drafts the discovery report** using the `user-interview-synthesis` skill
|
||||
6. **Identifies follow-up questions** for the next round of interviews
|
||||
7. **Saves the report** as a structured markdown document
|
||||
|
||||
End-to-end: roughly 3-5 minutes for 8-12 interview transcripts. The manual version of this synthesis takes most PMs a full day — and the inconsistency is the bigger problem than the time.
|
||||
|
||||
---
|
||||
|
||||
## Why this matters
|
||||
|
||||
Customer discovery is the workflow PMs say they care about most and consistently underinvest in. The reasons are predictable: synthesis is hard, themes are easy to over-interpret, confirmation bias is real, and writing it up takes hours. So PMs do interviews, take notes, and never come back to them properly.
|
||||
|
||||
This agent doesn't replace the discovery work. It removes the synthesis bottleneck so the discovery work actually pays off.
|
||||
|
||||
---
|
||||
|
||||
## What's inside this template
|
||||
|
||||
```
|
||||
templates/pm-discovery-agent/
|
||||
├── README.md ← you are here
|
||||
├── AGENT.md ← agent definition (system prompt + tool list)
|
||||
├── orchestrate.sh ← orchestration script
|
||||
├── skills/ ← skills used by this agent
|
||||
│ ├── README.md
|
||||
│ ├── discovery-interview-guide/SKILL.md ← (symlink)
|
||||
│ ├── user-interview-synthesis/SKILL.md ← (symlink)
|
||||
│ ├── job-story-mapper/SKILL.md ← (symlink)
|
||||
│ └── assumption-mapper/SKILL.md ← (symlink)
|
||||
├── subagents/
|
||||
│ ├── theme-synthesiser.md ← cross-interview theme detection
|
||||
│ └── assumption-scorer.md ← confidence scoring for findings
|
||||
├── connectors/
|
||||
│ ├── README.md ← connector setup guide
|
||||
│ ├── notion.example.json ← Notion database connector
|
||||
│ └── google-drive.example.json ← Google Drive folder connector
|
||||
├── examples/
|
||||
│ ├── input-example.md ← what you feed the agent
|
||||
│ ├── output-example.md ← what the agent produces
|
||||
│ └── sample-interview.md ← example interview note format
|
||||
└── tests/
|
||||
└── smoke-test.md ← manual smoke test for new installations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick install (5 minutes)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Claude Code installed
|
||||
- The full skills library installed: `/plugin marketplace add mohitagw15856/pm-claude-skills`
|
||||
- Either a Notion workspace or Google Drive (most PMs have both)
|
||||
|
||||
### Setup
|
||||
|
||||
**Choose your input source.** PMs typically store interview notes in one of two places:
|
||||
|
||||
- **Notion** — if you keep interviews in a Notion database (most common for PMs at scaleups)
|
||||
- **Google Drive** — if you keep interviews as Google Docs in a folder (most common for PMs at startups and large enterprises)
|
||||
|
||||
Set up the connector for whichever one you use. You don't need both.
|
||||
|
||||
### Notion setup (5 minutes)
|
||||
|
||||
```bash
|
||||
cd templates/pm-discovery-agent/connectors
|
||||
cp notion.example.json notion.json
|
||||
# Edit notion.json with your database_id and page properties
|
||||
```
|
||||
|
||||
Detailed setup steps in `connectors/README.md`.
|
||||
|
||||
### Google Drive setup (5 minutes)
|
||||
|
||||
```bash
|
||||
cd templates/pm-discovery-agent/connectors
|
||||
cp google-drive.example.json google-drive.json
|
||||
# Edit with your folder_id and authentication details
|
||||
```
|
||||
|
||||
### Test the smoke test
|
||||
|
||||
```bash
|
||||
cd templates/pm-discovery-agent
|
||||
bash orchestrate.sh --research-question "Test discovery synthesis" --dry-run
|
||||
```
|
||||
|
||||
If the dry-run completes without errors, you're ready to run a real discovery synthesis.
|
||||
|
||||
---
|
||||
|
||||
## Running the agent
|
||||
|
||||
### Standard usage
|
||||
|
||||
```bash
|
||||
bash orchestrate.sh \
|
||||
--research-question "Why are users abandoning the onboarding flow?" \
|
||||
--interview-source notion \
|
||||
--interview-count 10
|
||||
```
|
||||
|
||||
The agent will:
|
||||
|
||||
1. Pull the latest 10 interview notes from your configured Notion database
|
||||
2. Run the Theme Synthesiser subagent to identify patterns across interviews
|
||||
3. Run the `job-story-mapper` skill to convert findings into structured job stories
|
||||
4. Run the Assumption Scorer subagent to flag which findings are high vs low confidence
|
||||
5. Run the `user-interview-synthesis` skill to draft the final report
|
||||
6. Identify follow-up questions for the next round of interviews
|
||||
7. Save the report to `output/discovery-[date].md`
|
||||
|
||||
### Configuration options
|
||||
|
||||
| Flag | Required | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `--research-question` | Yes | — | The question your discovery is trying to answer |
|
||||
| `--interview-source` | Yes | — | `notion` or `google-drive` |
|
||||
| `--interview-count` | No | 8 | How many interviews to include in synthesis |
|
||||
| `--filter-by-segment` | No | — | If your notes are tagged by segment, filter to one (e.g., "enterprise") |
|
||||
| `--include-low-confidence` | No | true | Include low-confidence findings in the report (with explicit flagging) |
|
||||
| `--dry-run` | No | false | Validate config without running the workflow |
|
||||
|
||||
---
|
||||
|
||||
## How interview notes should be structured
|
||||
|
||||
The agent works best when interview notes follow a consistent structure. There's no rigid format required, but the more your notes contain, the better the synthesis.
|
||||
|
||||
**Minimum requirements** (the agent will work with any notes that have these):
|
||||
- Interviewee identifier (name, role, or anonymous ID)
|
||||
- Date of interview
|
||||
- Free-text notes or transcript
|
||||
|
||||
**Recommended additions** (for better synthesis):
|
||||
- Segment or persona tags
|
||||
- Key quotes pulled out
|
||||
- Initial interpretations or hypotheses
|
||||
- Follow-up questions noted
|
||||
|
||||
See `examples/sample-interview.md` for a template you can use to standardise your team's interview notes.
|
||||
|
||||
---
|
||||
|
||||
## Why this architecture
|
||||
|
||||
The template follows the same three-component pattern as PM Sprint Agent:
|
||||
|
||||
**Skills** provide the structured output formats. The `user-interview-synthesis` skill knows what a good discovery report contains. The `job-story-mapper` knows the JTBD format. The `assumption-mapper` knows how to structure assumptions. These already exist in this library — the agent doesn't reinvent them.
|
||||
|
||||
**Connectors** provide governed access to data. Notion and Google Drive are where PMs actually keep interview notes. Credentials live in environment variables, never in prompts.
|
||||
|
||||
**Subagents** handle specialised analysis. Theme synthesis across 10 interviews requires holding 10 documents in mind and finding patterns — that's a focused job for a subagent with a specific system prompt. Confidence scoring requires distinguishing "5 people said this" from "1 person said this dramatically" — also a focused job for a subagent.
|
||||
|
||||
---
|
||||
|
||||
## Customisation
|
||||
|
||||
### Adapt to your team's discovery process
|
||||
|
||||
The default agent uses the generic discovery skills from the main library. If your team has specific conventions — particular persona definitions, opportunity scoring frameworks, ICE prioritisation for follow-ups — fork the relevant skill into `skills/` and modify it. The orchestrate script will pick up the local version.
|
||||
|
||||
### Add additional analysis steps
|
||||
|
||||
If your discovery process includes things this template doesn't cover — competitive mention extraction, willingness-to-pay analysis, feature request triage — add subagents in `subagents/` for those analyses and update `orchestrate.sh` to call them.
|
||||
|
||||
### Switch interview sources
|
||||
|
||||
If you use a tool other than Notion or Google Drive — Dovetail, Granola, Otter, Reflect, Roam, Coda — you can build a connector following the pattern in `connectors/README.md`. PRs welcome for additional connectors.
|
||||
|
||||
---
|
||||
|
||||
## Limitations and honest caveats
|
||||
|
||||
**The synthesis is only as good as the notes.** If your interview notes are sparse, generic, or inconsistent in format, the synthesis will reflect that. Spending 15 minutes after each interview to write proper notes pays off enormously when you run the agent.
|
||||
|
||||
**Theme synthesis can over-cluster.** The Theme Synthesiser will find patterns even in small datasets. If you're running it on 3 interviews, treat the themes as hypotheses to validate, not conclusions. The agent flags this when interview count is low.
|
||||
|
||||
**Confidence scoring is heuristic, not statistical.** The Assumption Scorer uses simple rules — how many people mentioned it, how strongly, how recently. It's not running statistical analysis. Use the scores as a directional ranking, not a precise measurement.
|
||||
|
||||
**No autonomous execution.** This template runs as a Claude Code plugin — it produces outputs for human review, it doesn't autonomously create JIRA tickets or modify your discovery database. For autonomous execution, deploy via Claude Managed Agents using the same skills, connectors, and subagent definitions.
|
||||
|
||||
---
|
||||
|
||||
## Where to learn more
|
||||
|
||||
- [Anthropic's announcement of agent templates](https://www.anthropic.com/news/finance-agents) (May 2026)
|
||||
- [The PM Sprint Agent template](../pm-sprint-agent/) (first template in this library)
|
||||
- [The pm-claude-skills main README](../../README.md)
|
||||
- [Part 17 article — Building the PM Discovery Agent](#) *(link added when published)*
|
||||
|
||||
---
|
||||
|
||||
*Built and maintained by [Mohit Aggarwal](https://medium.com/@mohit15856) | Second agent template in [pm-claude-skills](https://github.com/mohitagw15856/pm-claude-skills)*
|
||||
@@ -0,0 +1,169 @@
|
||||
# Connectors — PM Discovery Agent
|
||||
|
||||
This folder contains the connector configurations for the PM Discovery Agent. You only need to set up the connector for whichever tool your team uses for interview notes — Notion or Google Drive.
|
||||
|
||||
## Which connector should I use?
|
||||
|
||||
| If your interview notes live in... | Use this connector |
|
||||
|---|---|
|
||||
| A Notion database | `notion.json` |
|
||||
| A Google Drive folder of Google Docs | `google-drive.json` |
|
||||
| Both | Pick the one with more interviews — agents work better with more data |
|
||||
| Somewhere else (Dovetail, Granola, Otter, etc.) | See "Building a connector for another system" below |
|
||||
|
||||
## Notion setup (5 minutes)
|
||||
|
||||
This is the fastest path if you keep interviews in Notion.
|
||||
|
||||
### 1. Create a Notion integration
|
||||
|
||||
- Go to https://www.notion.so/my-integrations
|
||||
- Click "+ New integration"
|
||||
- Name it "PM Discovery Agent"
|
||||
- Leave defaults
|
||||
- Click Submit
|
||||
- Copy the "Internal Integration Token" (starts with `secret_`)
|
||||
|
||||
### 2. Set the environment variable
|
||||
|
||||
```bash
|
||||
export NOTION_INTEGRATION_TOKEN='secret_xxxxxxxxxxxxxxxxxxxxxxxx'
|
||||
```
|
||||
|
||||
To make permanent, add to `~/.zshrc` or `~/.bashrc`.
|
||||
|
||||
### 3. Share your interview database with the integration
|
||||
|
||||
- Open your interview notes database in Notion
|
||||
- Click the `...` menu in the top right
|
||||
- Select "Add connections"
|
||||
- Choose "PM Discovery Agent"
|
||||
|
||||
The integration now has access to that database.
|
||||
|
||||
### 4. Find your database ID
|
||||
|
||||
The database ID is in the URL when viewing the database. Format: `notion.so/your-workspace/DATABASE_ID?v=...`
|
||||
|
||||
The ID is the long string between `/` and `?`. Copy it.
|
||||
|
||||
### 5. Configure the connector
|
||||
|
||||
```bash
|
||||
cp notion.example.json notion.json
|
||||
```
|
||||
|
||||
Open `notion.json` and update:
|
||||
- `database_id` — paste the ID from step 4
|
||||
- `expected_properties` — adjust to match your actual property names (the defaults assume Name, Interview Date, Interviewee, Segment, Status, Tags)
|
||||
|
||||
### 6. Test
|
||||
|
||||
```bash
|
||||
cd ../ # back to pm-discovery-agent root
|
||||
bash orchestrate.sh --research-question "Test" --interview-source notion --dry-run
|
||||
```
|
||||
|
||||
If you see "✓ Dry-run complete", you're set up.
|
||||
|
||||
## Google Drive setup (10 minutes)
|
||||
|
||||
A bit more setup than Notion, but works well if your team uses Google Docs for interviews.
|
||||
|
||||
### 1. Create a Google Cloud project
|
||||
|
||||
- Go to https://console.cloud.google.com/
|
||||
- Click "Select a project" > "New Project"
|
||||
- Name it "PM Discovery Agent"
|
||||
- Click Create
|
||||
|
||||
### 2. Enable the APIs
|
||||
|
||||
- In the project, search for "Google Drive API" in the API library
|
||||
- Click Enable
|
||||
- Search for "Google Docs API"
|
||||
- Click Enable
|
||||
|
||||
### 3. Create a service account
|
||||
|
||||
- Go to IAM & Admin > Service Accounts
|
||||
- Click "+ Create Service Account"
|
||||
- Name: "pm-discovery-reader"
|
||||
- Description: "Read-only access for PM Discovery Agent"
|
||||
- Click Create
|
||||
- Skip the optional permissions step
|
||||
- Click Done
|
||||
|
||||
### 4. Download the service account key
|
||||
|
||||
- Click on the service account you just created
|
||||
- Go to the "Keys" tab
|
||||
- Click "Add Key" > "Create new key"
|
||||
- Choose JSON
|
||||
- Save the file somewhere secure (e.g., `~/.config/pm-discovery-agent/service-account.json`)
|
||||
|
||||
### 5. Set the environment variable
|
||||
|
||||
```bash
|
||||
export GOOGLE_APPLICATION_CREDENTIALS='/Users/yourname/.config/pm-discovery-agent/service-account.json'
|
||||
```
|
||||
|
||||
To make permanent, add to `~/.zshrc` or `~/.bashrc`.
|
||||
|
||||
### 6. Share your interview folder with the service account
|
||||
|
||||
- Find the service account email (it looks like `pm-discovery-reader@your-project.iam.gserviceaccount.com`)
|
||||
- Open your interview notes folder in Google Drive
|
||||
- Click Share
|
||||
- Paste the service account email
|
||||
- Set permission to Viewer
|
||||
- Click Send
|
||||
|
||||
### 7. Find your folder ID
|
||||
|
||||
Open the folder in Google Drive. The URL looks like: `drive.google.com/drive/folders/FOLDER_ID_HERE`
|
||||
|
||||
Copy the ID after `/folders/`.
|
||||
|
||||
### 8. Configure the connector
|
||||
|
||||
```bash
|
||||
cp google-drive.example.json google-drive.json
|
||||
```
|
||||
|
||||
Open `google-drive.json` and update:
|
||||
- `folder_id` — paste the ID from step 7
|
||||
|
||||
### 9. Test
|
||||
|
||||
```bash
|
||||
cd ../ # back to pm-discovery-agent root
|
||||
bash orchestrate.sh --research-question "Test" --interview-source google-drive --dry-run
|
||||
```
|
||||
|
||||
## Building a connector for another system
|
||||
|
||||
If your interview notes live somewhere other than Notion or Google Drive, you can build a connector following the same pattern. Common alternatives PMs use:
|
||||
|
||||
- **Dovetail** — has a research API; build a connector for the analysis endpoint
|
||||
- **Granola / Otter / Fathom** — meeting recorders; build a connector that pulls transcripts
|
||||
- **Reflect / Roam / Logseq** — personal note-taking apps; build a connector for the markdown files
|
||||
- **Coda / Airtable** — alternative databases; build a connector for the rows API
|
||||
- **Local files** — markdown files in a folder; build a simple file-reading connector
|
||||
|
||||
A connector needs three things:
|
||||
1. A configuration file defining the data source URL, credentials, and available operations
|
||||
2. An API client the orchestration script can call
|
||||
3. A mapping from the source's data model to what the agent expects (interview ID, date, interviewee, content, tags)
|
||||
|
||||
Copy `notion.example.json` or `google-drive.example.json` as a starting point.
|
||||
|
||||
If you build a connector for a new system, consider raising a PR back to the main pm-claude-skills repo.
|
||||
|
||||
## Security notes
|
||||
|
||||
**Credentials live in environment variables, not in the JSON files.** This means you can commit your `notion.json` or `google-drive.json` to source control without leaking credentials.
|
||||
|
||||
**Use read-only access where possible.** The agent only needs to read interview notes — never to modify them. Both Notion integrations and Google Drive service accounts can be set up with read-only permissions. Use them.
|
||||
|
||||
**Rotate credentials periodically.** Both Notion integration tokens and Google service account keys can be regenerated. Do this every 90 days as a security practice.
|
||||
@@ -0,0 +1,86 @@
|
||||
{
|
||||
"connector_name": "google-drive",
|
||||
"version": "1.0.0",
|
||||
"description": "Google Drive connector for the PM Discovery Agent. Reads interview notes from a Google Drive folder where each interview is a Google Doc.",
|
||||
|
||||
"configuration": {
|
||||
"folder_id": "FOLDER_ID_HERE",
|
||||
"file_type": "application/vnd.google-apps.document",
|
||||
"include_subfolders": false,
|
||||
"expected_naming_convention": "YYYY-MM-DD - Interviewee Name.gdoc",
|
||||
"default_sort": {
|
||||
"field": "modifiedTime",
|
||||
"direction": "desc"
|
||||
},
|
||||
"default_filters": {
|
||||
"exclude_trashed": true,
|
||||
"min_word_count": 100
|
||||
},
|
||||
"rate_limit_requests_per_minute": 60
|
||||
},
|
||||
|
||||
"credentials": {
|
||||
"_comment": "Google Drive uses OAuth 2.0. You'll need to create a Google Cloud project and enable the Drive API. Easiest path: use a service account with access to your folder.",
|
||||
"auth_method": "service_account",
|
||||
"service_account_key_path_env_var": "GOOGLE_APPLICATION_CREDENTIALS",
|
||||
"service_account_key_placeholder": "/path/to/service-account-key.json"
|
||||
},
|
||||
|
||||
"available_operations": [
|
||||
{
|
||||
"name": "list_recent_documents",
|
||||
"description": "Get the N most recent Google Docs in the configured folder",
|
||||
"filters": ["modifiedAfter", "name_contains", "starred"],
|
||||
"max_results": 50
|
||||
},
|
||||
{
|
||||
"name": "get_document_content",
|
||||
"description": "Fetch the full text content of a specific Google Doc",
|
||||
"required_input": "file_id"
|
||||
},
|
||||
{
|
||||
"name": "search_documents",
|
||||
"description": "Search document content by keyword across the folder",
|
||||
"required_input": "search_query"
|
||||
}
|
||||
],
|
||||
|
||||
"permissions_required": [
|
||||
"https://www.googleapis.com/auth/drive.readonly",
|
||||
"https://www.googleapis.com/auth/documents.readonly"
|
||||
],
|
||||
|
||||
"_setup_instructions": [
|
||||
"1. Go to Google Cloud Console: https://console.cloud.google.com/",
|
||||
"2. Create a new project (or use existing) — name it something like 'PM Discovery Agent'",
|
||||
"3. Enable the Google Drive API and Google Docs API for the project",
|
||||
"4. Create a service account: IAM & Admin > Service Accounts > Create Service Account",
|
||||
"5. Download the service account key as JSON",
|
||||
"6. Save the JSON file to a secure location (e.g., ~/.config/pm-discovery-agent/service-account.json)",
|
||||
"7. Set the environment variable: export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account.json'",
|
||||
"8. Find the folder ID where your interview notes live: open the folder in Google Drive, the ID is in the URL (drive.google.com/drive/folders/FOLDER_ID_HERE)",
|
||||
"9. Share that folder with the service account email (it looks like xxx@your-project.iam.gserviceaccount.com) — give it Viewer access",
|
||||
"10. Update folder_id in this file",
|
||||
"11. Save this file as 'google-drive.json' (without the .example)",
|
||||
"12. Test the connection: bash orchestrate.sh --research-question 'Test' --interview-source google-drive --dry-run"
|
||||
],
|
||||
|
||||
"_alternative_simpler_setup": [
|
||||
"If creating a service account feels heavy, you can use OAuth user credentials instead:",
|
||||
"1. Go to APIs & Services > Credentials in Google Cloud Console",
|
||||
"2. Create OAuth client ID > Desktop application",
|
||||
"3. Download the credentials JSON",
|
||||
"4. The first time the agent runs, it'll open a browser for you to authorise",
|
||||
"This is simpler but requires re-authorisation if the token expires."
|
||||
],
|
||||
|
||||
"_folder_organisation_recommendation": [
|
||||
"If you're starting fresh, organise your interview notes folder like this:",
|
||||
"- One folder for the discovery project",
|
||||
"- One Google Doc per interview, named '2026-05-10 - Sarah Chen.gdoc' (date + interviewee)",
|
||||
"- Inside each doc: structured headers for Background, Notes, Key Quotes, Observations, Follow-ups",
|
||||
"Consistent structure makes the synthesis dramatically better."
|
||||
],
|
||||
|
||||
"_rate_limit_notes": "Google Drive's API rate limits are generous (1000 requests per 100 seconds). The agent uses approximately 12-15 API calls per discovery synthesis."
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
{
|
||||
"connector_name": "notion",
|
||||
"version": "1.0.0",
|
||||
"description": "Notion connector for the PM Discovery Agent. Reads interview notes from a Notion database where each interview is a database row.",
|
||||
|
||||
"configuration": {
|
||||
"database_id": "DATABASE_ID_HERE",
|
||||
"workspace_url": "https://www.notion.so/your-workspace",
|
||||
"expected_properties": {
|
||||
"title_property": "Name",
|
||||
"date_property": "Interview Date",
|
||||
"interviewee_property": "Interviewee",
|
||||
"segment_property": "Segment",
|
||||
"status_property": "Status",
|
||||
"tags_property": "Tags"
|
||||
},
|
||||
"default_filters": {
|
||||
"status_is": "Completed",
|
||||
"exclude_archived": true
|
||||
},
|
||||
"default_sort": {
|
||||
"property": "Interview Date",
|
||||
"direction": "descending"
|
||||
},
|
||||
"rate_limit_requests_per_second": 3
|
||||
},
|
||||
|
||||
"credentials": {
|
||||
"_comment": "Notion uses an integration token. Create one at https://www.notion.so/my-integrations and share your database with it.",
|
||||
"integration_token_env_var": "NOTION_INTEGRATION_TOKEN",
|
||||
"integration_token_placeholder": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||
},
|
||||
|
||||
"available_operations": [
|
||||
{
|
||||
"name": "list_recent_interviews",
|
||||
"description": "Get the N most recent interviews from the configured database",
|
||||
"filters": ["segment", "tags", "date_range", "status"],
|
||||
"max_results": 50
|
||||
},
|
||||
{
|
||||
"name": "get_interview_content",
|
||||
"description": "Fetch the full page content of a specific interview (notes, transcript, observations)",
|
||||
"required_input": "page_id"
|
||||
},
|
||||
{
|
||||
"name": "search_interviews",
|
||||
"description": "Search interview content by keyword",
|
||||
"required_input": "search_query"
|
||||
}
|
||||
],
|
||||
|
||||
"permissions_required": [
|
||||
"Read content",
|
||||
"Read user information without email"
|
||||
],
|
||||
|
||||
"_setup_instructions": [
|
||||
"1. Create a Notion integration at https://www.notion.so/my-integrations",
|
||||
"2. Click '+ New integration', name it 'PM Discovery Agent', leave defaults",
|
||||
"3. After creation, copy the Internal Integration Token (starts with 'secret_')",
|
||||
"4. Set the environment variable: export NOTION_INTEGRATION_TOKEN='secret_xxxxx...'",
|
||||
"5. Open your interview notes database in Notion",
|
||||
"6. Click '...' menu in top right > 'Add connections' > select your new integration",
|
||||
"7. Find your database ID: it's the long string in the URL when viewing the database (after the workspace name and before the '?'). Example: notion.so/workspace/abc123def456 — abc123def456 is the ID",
|
||||
"8. Update database_id in this file",
|
||||
"9. Update expected_properties to match your actual property names (the agent expects fields named Name, Interview Date, Interviewee, Segment, Status, Tags — adjust if yours are different)",
|
||||
"10. Save this file as 'notion.json' (without the .example)",
|
||||
"11. Test the connection: bash orchestrate.sh --research-question 'Test' --interview-source notion --dry-run"
|
||||
],
|
||||
|
||||
"_notion_database_setup_recommendation": [
|
||||
"If you don't have a Notion database for interviews yet, create one with these properties:",
|
||||
"- Name (title) — interview identifier or interviewee name",
|
||||
"- Interview Date (date) — when the interview happened",
|
||||
"- Interviewee (text) — who was interviewed",
|
||||
"- Segment (select) — which user segment they belong to",
|
||||
"- Status (select) — Scheduled / Completed / Cancelled",
|
||||
"- Tags (multi-select) — research project, persona, or feature area",
|
||||
"Then write your interview notes in the page body."
|
||||
],
|
||||
|
||||
"_rate_limit_notes": "Notion's API is rate limited to 3 requests per second per integration. The agent typically uses 10-25 API calls per discovery synthesis (depending on interview count), well within rate limits."
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
# Example: Input to the PM Discovery Agent
|
||||
|
||||
## Command-line invocation
|
||||
|
||||
```bash
|
||||
bash orchestrate.sh \
|
||||
--research-question "Why are users abandoning the onboarding flow?" \
|
||||
--interview-source notion \
|
||||
--interview-count 10 \
|
||||
--filter-by-segment "smb"
|
||||
```
|
||||
|
||||
## What the agent reads from your connector
|
||||
|
||||
### From Notion
|
||||
|
||||
The agent automatically pulls from your configured Notion database:
|
||||
|
||||
- Most recent N interviews where Status = "Completed"
|
||||
- For each interview:
|
||||
- Title (interviewee name or identifier)
|
||||
- Interview date
|
||||
- Interviewee role and segment tags
|
||||
- Full page content (notes, transcript, observations, quotes)
|
||||
|
||||
If you've applied a segment filter, only interviews matching that segment are included.
|
||||
|
||||
### From Google Drive
|
||||
|
||||
The agent automatically pulls from your configured folder:
|
||||
|
||||
- Most recently modified Google Docs in the folder
|
||||
- For each doc:
|
||||
- Document title
|
||||
- Last modified date
|
||||
- Full text content
|
||||
|
||||
If your filenames follow the `YYYY-MM-DD - Name.gdoc` convention, the agent uses the date for sorting and the name for interviewee identification.
|
||||
|
||||
## What the agent does NOT need from you
|
||||
|
||||
- A summary of what the interviews said — that's what the agent produces
|
||||
- Pre-tagged themes — the agent finds them
|
||||
- A list of which interviews are most important — the agent uses all included interviews
|
||||
- Statistical analysis — this is qualitative discovery, not quantitative
|
||||
|
||||
## What you should know before running
|
||||
|
||||
- **Have at least 5 interviews completed.** The agent works best with 5+ interviews. With fewer, themes will be tagged as "Emerging" rather than "Strong" — directional insights only.
|
||||
- **Have a specific research question.** Vague questions produce vague synthesis. "What do users think?" is too broad. "Why are users abandoning the onboarding flow at step 3?" is specific enough to drive useful synthesis.
|
||||
- **Check your interview notes are accessible.** The agent can only read what your connector has access to. If notes are in a different database/folder than configured, results will be empty.
|
||||
|
||||
## Example: Real-world invocations
|
||||
|
||||
```bash
|
||||
# Standard discovery synthesis from Notion
|
||||
bash orchestrate.sh \
|
||||
--research-question "What's blocking users from completing checkout?" \
|
||||
--interview-source notion \
|
||||
--interview-count 8
|
||||
|
||||
# Synthesis filtered to a specific segment
|
||||
bash orchestrate.sh \
|
||||
--research-question "How are enterprise customers using the API?" \
|
||||
--interview-source notion \
|
||||
--interview-count 12 \
|
||||
--filter-by-segment "enterprise"
|
||||
|
||||
# Synthesis from Google Drive folder (all recent interviews)
|
||||
bash orchestrate.sh \
|
||||
--research-question "What workflows do power users have that we don't support?" \
|
||||
--interview-source google-drive \
|
||||
--interview-count 10
|
||||
|
||||
# Smaller batch with low-confidence findings excluded (cleaner stakeholder report)
|
||||
bash orchestrate.sh \
|
||||
--research-question "Validate our pricing hypothesis" \
|
||||
--interview-source notion \
|
||||
--interview-count 6 \
|
||||
--include-low-confidence false
|
||||
|
||||
# Dry run to validate config
|
||||
bash orchestrate.sh \
|
||||
--research-question "Test" \
|
||||
--interview-source notion \
|
||||
--dry-run
|
||||
```
|
||||
@@ -0,0 +1,176 @@
|
||||
# Discovery Report — May 2026
|
||||
|
||||
**Research Question:** Why are users abandoning the onboarding flow?
|
||||
**Interview Source:** notion
|
||||
**Interview Count:** 10
|
||||
**Generated:** 2026-05-06 14:30 BST
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Across 10 SMB customer interviews, three high-confidence findings emerged about onboarding abandonment:
|
||||
|
||||
1. **Users feel they're being asked to commit before understanding what they're getting.** The current flow asks for credit card details and integration setup before showing any value. 8 of 10 interviews mentioned this directly.
|
||||
|
||||
2. **The integration setup step is the highest-friction point.** Users are willing to set up integrations once they're convinced of value — but doing it before that point feels like extra work for no clear payoff. 7 of 10 interviews mentioned this.
|
||||
|
||||
3. **The pricing display creates anxiety, not clarity.** Showing pricing tiers without clear differentiation between them creates decision paralysis. 6 of 10 interviews described this.
|
||||
|
||||
Two medium-confidence findings worth validating in the next research round:
|
||||
- Users may be abandoning because they confuse onboarding with set-up (5 interviews)
|
||||
- The "skip for now" option may be reducing completion rather than helping (4 interviews)
|
||||
|
||||
---
|
||||
|
||||
## Themes Identified
|
||||
|
||||
### Theme 1: Premature commitment ask (Strong)
|
||||
|
||||
Users feel they're being asked to commit (credit card, integrations, team invites) before they understand what they're getting from the product.
|
||||
|
||||
- **Supporting interviews:** 8 — IDs: I-103, I-105, I-107, I-109, I-110, I-112, I-114, I-115
|
||||
- **Strength:** Strong
|
||||
- **Quotes:**
|
||||
- "I just wanted to see if this would work for my team. Why am I being asked for my credit card?" — I-105
|
||||
- "It felt like I was already a customer before I'd even decided." — I-110
|
||||
- "The first thing it asked me was to invite my whole team. I haven't even tried it yet." — I-114
|
||||
- **Contradicting evidence:** None
|
||||
- **Why this matters:** This is the strongest signal in the synthesis. The team should consider redesigning the flow so users see value before being asked to commit.
|
||||
|
||||
### Theme 2: Integration setup friction (Strong)
|
||||
|
||||
The integration setup step (connecting to Slack, Google Drive, etc.) is happening too early in the flow. Users are willing to set up integrations once convinced, but doing it before is friction.
|
||||
|
||||
- **Supporting interviews:** 7 — IDs: I-103, I-105, I-109, I-110, I-112, I-114, I-115
|
||||
- **Strength:** Strong
|
||||
- **Quotes:**
|
||||
- "I gave up at the Slack integration step. I wasn't sure I wanted my team to know I was trying this yet." — I-109
|
||||
- "Why does it need access to my Google Drive before I've even seen what it does?" — I-103
|
||||
- **Contradicting evidence:** I-107 mentioned that integration setup felt natural — "I expected to connect my tools, that's normal." This is a single contradiction within the broader pattern.
|
||||
- **Why this matters:** This connects to Theme 1. Users want value first, commitment second.
|
||||
|
||||
### Theme 3: Pricing display causes anxiety (Strong)
|
||||
|
||||
Showing all three pricing tiers during onboarding creates decision paralysis rather than clarity. Users aren't sure which tier they need.
|
||||
|
||||
- **Supporting interviews:** 6 — IDs: I-105, I-107, I-110, I-112, I-114, I-115
|
||||
- **Strength:** Strong
|
||||
- **Quotes:**
|
||||
- "I don't know if I'm a Pro user or a Team user. I just wanted to try it." — I-107
|
||||
- "Showing me three columns of features I don't understand made me close the tab." — I-114
|
||||
- **Contradicting evidence:** None
|
||||
- **Why this matters:** The current pricing display is optimised for users who already know they want to buy. For first-time users, it's a distraction.
|
||||
|
||||
### Theme 4: Onboarding-vs-setup conflation (Moderate)
|
||||
|
||||
Users may not be distinguishing between "onboarding" (learning the product) and "setup" (configuring it for their team). They expected the first to come before the second.
|
||||
|
||||
- **Supporting interviews:** 5 — IDs: I-103, I-109, I-110, I-114, I-115
|
||||
- **Strength:** Moderate
|
||||
- **Quotes:**
|
||||
- "I thought I'd see how to use it. Instead I was configuring it." — I-115
|
||||
- "Onboarding should be 'here's what this does'. Not 'fill out these forms'." — I-103
|
||||
- **Contradicting evidence:** None — but this finding is partially redundant with Theme 1.
|
||||
- **Why this matters:** Could be reframed: the issue isn't onboarding vs. setup specifically — it's that setup is happening before value demonstration.
|
||||
|
||||
### Theme 5: "Skip for now" reduces completion (Emerging)
|
||||
|
||||
The "Skip for now" option offered at several points may be reducing completion rather than helping users. Users who skip rarely come back to complete those steps.
|
||||
|
||||
- **Supporting interviews:** 4 — IDs: I-105, I-110, I-112, I-114
|
||||
- **Strength:** Emerging
|
||||
- **Quotes:**
|
||||
- "I clicked Skip on three things. Then I forgot to come back." — I-110
|
||||
- **Contradicting evidence:** None — but only 4 interviews and behavioural data would validate this better than interview observations.
|
||||
- **Why this matters:** If validated, this suggests the team should either remove the skip option or implement reminders.
|
||||
|
||||
---
|
||||
|
||||
## Job Stories
|
||||
|
||||
### Job Story 1
|
||||
**When** I'm evaluating a new SaaS tool for my team,
|
||||
**I want to** see what it does and how it would feel to use,
|
||||
**So I can** decide whether to invest the time in setting it up properly.
|
||||
|
||||
### Job Story 2
|
||||
**When** I'm in the early evaluation phase of a tool,
|
||||
**I want to** avoid commitments (payment, team invites, integrations),
|
||||
**So I can** stay in low-stakes exploration mode.
|
||||
|
||||
### Job Story 3
|
||||
**When** I'm shown pricing during evaluation,
|
||||
**I want to** understand which tier fits my situation without comparing all features,
|
||||
**So I can** focus on whether the product solves my problem.
|
||||
|
||||
---
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
| Finding | Confidence | Breadth | Quality | Contradictions |
|
||||
|---|---|---|---|---|
|
||||
| Premature commitment ask | High | 8 interviews | High | None |
|
||||
| Integration setup friction | High | 7 interviews | High | 1 (likely segment-specific) |
|
||||
| Pricing causes anxiety | High | 6 interviews | High | None |
|
||||
| Onboarding/setup conflation | Medium | 5 interviews | Medium | None — but redundant with Theme 1 |
|
||||
| "Skip for now" reduces completion | Low | 4 interviews | Medium | None — needs behavioural data |
|
||||
|
||||
### Recommended actions
|
||||
|
||||
- **High confidence findings:** Safe to use in product decisions. Can frame in stakeholder communications without caveat.
|
||||
- **Medium confidence findings:** Use directionally. Validate with one more interview round before major product decisions.
|
||||
- **Low confidence findings:** Treat as hypothesis. Do not use in product decisions until validated with behavioural analytics.
|
||||
|
||||
---
|
||||
|
||||
## Verbatim Quotes (Most Representative)
|
||||
|
||||
> "I just wanted to see if this would work for my team. Why am I being asked for my credit card?" — I-105
|
||||
|
||||
> "It felt like I was already a customer before I'd even decided." — I-110
|
||||
|
||||
> "The first thing it asked me was to invite my whole team. I haven't even tried it yet." — I-114
|
||||
|
||||
> "I don't know if I'm a Pro user or a Team user. I just wanted to try it." — I-107
|
||||
|
||||
> "Onboarding should be 'here's what this does'. Not 'fill out these forms'." — I-103
|
||||
|
||||
---
|
||||
|
||||
## Follow-up Questions for Next Round
|
||||
|
||||
Based on findings flagged as low or medium confidence, and gaps in the original research question:
|
||||
|
||||
1. **Validate "Skip for now" hypothesis:** Pair the next 5 interviews with behavioural analytics on completion rates for users who skip vs. don't skip. — Would validate Theme 5.
|
||||
|
||||
2. **Test the integration ordering:** What if integration setup came after the first value demonstration? Would users still be reluctant? — Would help design the redesigned flow.
|
||||
|
||||
3. **Probe enterprise users:** All 10 interviews were SMB. Do enterprise users have different expectations about commitment depth during evaluation? — Fills the segment gap.
|
||||
|
||||
4. **Validate the redundancy of Themes 1 and 4:** Are these the same finding stated differently, or genuinely separate? — Affects how we frame the findings to stakeholders.
|
||||
|
||||
5. **Understand competitive context:** Are users abandoning to try competitors, or just not coming back? — Would tell us if this is a problem of conversion specifically or activation more broadly.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Interview Summary
|
||||
|
||||
| ID | Date | Interviewee | Segment | Notes Length |
|
||||
|---|---|---|---|---|
|
||||
| I-103 | 2026-04-15 | David Park, founder | SMB | Substantial |
|
||||
| I-105 | 2026-04-17 | Sarah Lee, marketing manager | SMB | Substantial |
|
||||
| I-107 | 2026-04-18 | Marcus Wong, ops lead | SMB | Brief |
|
||||
| I-109 | 2026-04-22 | Priya Patel, team lead | SMB | Substantial |
|
||||
| I-110 | 2026-04-23 | Jamie Roberts, founder | SMB | Substantial |
|
||||
| I-112 | 2026-04-25 | Lin Chen, CTO | SMB | Substantial |
|
||||
| I-114 | 2026-04-28 | Tom Bradley, marketer | SMB | Substantial |
|
||||
| I-115 | 2026-04-30 | Aisha Khan, ops manager | SMB | Substantial |
|
||||
| I-117 | 2026-05-02 | (Excluded — test interview) | — | — |
|
||||
| I-118 | 2026-05-04 | (Excluded — segment mismatch, enterprise) | — | — |
|
||||
|
||||
8 of 10 interviews included in synthesis (2 excluded for the reasons above).
|
||||
|
||||
---
|
||||
|
||||
*Generated by [PM Discovery Agent](https://github.com/mohitagw15856/pm-claude-skills/tree/main/templates/pm-discovery-agent) — second agent template in pm-claude-skills*
|
||||
@@ -0,0 +1,95 @@
|
||||
# Sample Interview Note Format
|
||||
|
||||
This is a recommended structure for interview notes to maximise the quality of synthesis from the PM Discovery Agent. Use this as a template for your team.
|
||||
|
||||
The agent will work with notes in any format, but consistent structure dramatically improves results.
|
||||
|
||||
---
|
||||
|
||||
# Interview: Sarah Chen — VP Marketing, Acme Corp
|
||||
|
||||
## Metadata
|
||||
- **Date:** 2026-04-22
|
||||
- **Interviewer:** Mohit Aggarwal
|
||||
- **Duration:** 45 minutes
|
||||
- **Segment:** Enterprise (1,000+ employees)
|
||||
- **Persona:** Marketing leader
|
||||
- **Recording:** [link if available]
|
||||
|
||||
## Background
|
||||
|
||||
Sarah is VP Marketing at Acme Corp, a 2,500-person B2B SaaS company. She's been in role 18 months, previously held similar roles at two other companies. She manages a team of 12 marketers across content, demand gen, brand, and analyst relations.
|
||||
|
||||
We spoke as part of the discovery research into our planned content collaboration tool.
|
||||
|
||||
## Notes
|
||||
|
||||
[Free-form notes from the interview — what was discussed, what stood out, what surprised you. Aim for 500-1500 words depending on interview depth.]
|
||||
|
||||
Sarah opened with frustration about her team's content review process. She estimates that her team spends 30% of their time on internal coordination — getting reviews from product, legal, sales — rather than actually creating content.
|
||||
|
||||
The current process is: someone drafts in Google Docs, shares with reviewers, reviewers leave comments, the writer addresses comments, multiple back-and-forth rounds happen, eventually it ships. For a single piece of content, this can take 2-3 weeks.
|
||||
|
||||
The breaking point for her was a recent quarter where they tried to ship 8 thought leadership pieces tied to a product launch. They shipped 3. The other 5 are still in review purgatory months later.
|
||||
|
||||
When asked what would solve this, she didn't immediately reach for a tool — she reached for process. "We need clearer SLAs on review turnaround. We need to know who can approve what without escalating." Tools came up as a follow-up: "If there was something that gave us visibility into where each piece was stuck, that'd help."
|
||||
|
||||
She mentioned trialing several tools in the past: Workfront, Asana for marketing, Trello. None stuck. Her diagnosis was that they were good for tracking work but didn't actually solve the review bottleneck.
|
||||
|
||||
Interesting tangent: she mentioned that her best marketers have started bypassing the formal review process entirely, going to specific reviewers directly via Slack. This works for them but creates inconsistency and accountability gaps.
|
||||
|
||||
## Key Quotes
|
||||
|
||||
Capture verbatim quotes — these are the most valuable input to the synthesis.
|
||||
|
||||
> "We're not stuck because we don't have ideas. We're stuck because we can't get ideas through the system."
|
||||
|
||||
> "I've trialed every project management tool you can name. They're all great for tracking. None of them solve the actual problem, which is that humans don't review things on time."
|
||||
|
||||
> "My best marketer just sends Slack DMs to specific people. She gets her stuff out the door. But it's all dependent on her relationships."
|
||||
|
||||
> "I don't need another tool to add to my stack. I need something that makes the existing process actually work."
|
||||
|
||||
## Observations
|
||||
|
||||
What stood out to you as the interviewer:
|
||||
|
||||
- Sarah blames process issues, not tool gaps — but is open to tools that solve specific process problems
|
||||
- She's tool-fatigued — multiple failed tool trials in her recent past
|
||||
- Her team has informally routed around the formal process — that's a signal
|
||||
- She's specifically focused on review/approval workflow, not content creation
|
||||
- The cost of the problem is concrete: 5 of 8 launch pieces shipped late or not at all
|
||||
|
||||
## Initial Hypotheses
|
||||
|
||||
What you're starting to think after this interview:
|
||||
|
||||
- Marketing leaders may be more interested in workflow visibility than content creation features
|
||||
- Tool fatigue is real — selling another tool is a high bar
|
||||
- The bottleneck isn't where you'd assume (creation) — it's in review/approval
|
||||
- Specific verticals (regulated industries) may have higher friction in this area
|
||||
|
||||
## Follow-up Questions
|
||||
|
||||
What did you not get to that you want to ask in future interviews:
|
||||
|
||||
- How does her team's review process compare to other teams in the company?
|
||||
- What would she actually pay for if a solution existed?
|
||||
- Is the bypass behaviour a problem she's actively trying to solve, or has she accepted it?
|
||||
- How much of this is unique to enterprise size vs. universal across companies?
|
||||
|
||||
---
|
||||
|
||||
## Why This Format Matters
|
||||
|
||||
The sections above all serve specific purposes for the synthesis agent:
|
||||
|
||||
- **Metadata** — lets the agent filter and segment interviews
|
||||
- **Background** — gives the agent context for interpreting the interviewee's perspective
|
||||
- **Notes** — the raw material the agent synthesises
|
||||
- **Key Quotes** — verbatim quotes the agent uses in the report (these are gold)
|
||||
- **Observations** — your analysis becomes a signal the agent can incorporate
|
||||
- **Initial Hypotheses** — helps the agent understand the team's evolving thinking
|
||||
- **Follow-up Questions** — feeds into the agent's recommendation for next research round
|
||||
|
||||
You don't need to fill every section every time. The Notes and Key Quotes sections are the most important. Everything else is a bonus.
|
||||
Executable
+320
@@ -0,0 +1,320 @@
|
||||
#!/bin/bash
|
||||
|
||||
# =============================================================================
|
||||
# orchestrate.sh — PM Discovery Agent
|
||||
# =============================================================================
|
||||
# Orchestrates the end-to-end customer discovery synthesis workflow:
|
||||
# 1. Validate configuration and connector
|
||||
# 2. Pull interview notes from Notion or Google Drive
|
||||
# 3. Run Theme Synthesiser subagent
|
||||
# 4. Run job-story-mapper skill via Claude Code
|
||||
# 5. Run Assumption Scorer subagent
|
||||
# 6. Run user-interview-synthesis skill via Claude Code
|
||||
# 7. Generate follow-up questions
|
||||
# 8. Combine outputs into a discovery report
|
||||
#
|
||||
# Usage:
|
||||
# bash orchestrate.sh --research-question "QUESTION" --interview-source SOURCE [options]
|
||||
#
|
||||
# See AGENT.md for full documentation.
|
||||
# =============================================================================
|
||||
|
||||
set -e
|
||||
set -o pipefail
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Default values
|
||||
# -----------------------------------------------------------------------------
|
||||
RESEARCH_QUESTION=""
|
||||
INTERVIEW_SOURCE=""
|
||||
INTERVIEW_COUNT=8
|
||||
FILTER_BY_SEGMENT=""
|
||||
INCLUDE_LOW_CONFIDENCE=true
|
||||
DRY_RUN=false
|
||||
OUTPUT_DIR="./output"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Parse command-line arguments
|
||||
# -----------------------------------------------------------------------------
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--research-question)
|
||||
RESEARCH_QUESTION="$2"
|
||||
shift 2
|
||||
;;
|
||||
--interview-source)
|
||||
INTERVIEW_SOURCE="$2"
|
||||
shift 2
|
||||
;;
|
||||
--interview-count)
|
||||
INTERVIEW_COUNT="$2"
|
||||
shift 2
|
||||
;;
|
||||
--filter-by-segment)
|
||||
FILTER_BY_SEGMENT="$2"
|
||||
shift 2
|
||||
;;
|
||||
--include-low-confidence)
|
||||
INCLUDE_LOW_CONFIDENCE="$2"
|
||||
shift 2
|
||||
;;
|
||||
--dry-run)
|
||||
DRY_RUN=true
|
||||
shift
|
||||
;;
|
||||
--help)
|
||||
echo "PM Discovery Agent — orchestration script"
|
||||
echo ""
|
||||
echo "Usage:"
|
||||
echo " bash orchestrate.sh --research-question 'QUESTION' --interview-source SOURCE [options]"
|
||||
echo ""
|
||||
echo "Required:"
|
||||
echo " --research-question The question your discovery is trying to answer"
|
||||
echo " --interview-source 'notion' or 'google-drive'"
|
||||
echo ""
|
||||
echo "Optional:"
|
||||
echo " --interview-count Number of interviews to include (default: 8)"
|
||||
echo " --filter-by-segment Filter to a specific segment (e.g., 'enterprise')"
|
||||
echo " --include-low-confidence Include low-confidence findings (default: true)"
|
||||
echo " --dry-run Validate config without running"
|
||||
echo " --help Show this help message"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
echo "Unknown option: $1"
|
||||
echo "Run 'bash orchestrate.sh --help' for usage"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Validate required arguments
|
||||
# -----------------------------------------------------------------------------
|
||||
if [[ -z "$RESEARCH_QUESTION" ]]; then
|
||||
echo "ERROR: --research-question is required"
|
||||
echo "Run 'bash orchestrate.sh --help' for usage"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ -z "$INTERVIEW_SOURCE" ]]; then
|
||||
echo "ERROR: --interview-source is required ('notion' or 'google-drive')"
|
||||
echo "Run 'bash orchestrate.sh --help' for usage"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$INTERVIEW_SOURCE" != "notion" ]] && [[ "$INTERVIEW_SOURCE" != "google-drive" ]]; then
|
||||
echo "ERROR: --interview-source must be 'notion' or 'google-drive'"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Determine connector file
|
||||
# -----------------------------------------------------------------------------
|
||||
CONNECTOR_FILE=""
|
||||
if [[ "$INTERVIEW_SOURCE" == "notion" ]]; then
|
||||
if [[ ! -f "./connectors/notion.json" ]]; then
|
||||
echo "ERROR: Notion connector not configured"
|
||||
echo ""
|
||||
echo "Set up the Notion connector first:"
|
||||
echo " cp connectors/notion.example.json connectors/notion.json"
|
||||
echo " # Then edit connectors/notion.json with your database details"
|
||||
echo ""
|
||||
echo "See connectors/README.md for full setup instructions."
|
||||
exit 1
|
||||
fi
|
||||
CONNECTOR_FILE="./connectors/notion.json"
|
||||
elif [[ "$INTERVIEW_SOURCE" == "google-drive" ]]; then
|
||||
if [[ ! -f "./connectors/google-drive.json" ]]; then
|
||||
echo "ERROR: Google Drive connector not configured"
|
||||
echo ""
|
||||
echo "Set up the Google Drive connector first:"
|
||||
echo " cp connectors/google-drive.example.json connectors/google-drive.json"
|
||||
echo " # Then edit with your folder ID"
|
||||
echo ""
|
||||
echo "See connectors/README.md for full setup instructions."
|
||||
exit 1
|
||||
fi
|
||||
CONNECTOR_FILE="./connectors/google-drive.json"
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Validate credentials are set
|
||||
# -----------------------------------------------------------------------------
|
||||
if [[ "$INTERVIEW_SOURCE" == "notion" ]]; then
|
||||
if [[ -z "${NOTION_INTEGRATION_TOKEN:-}" ]]; then
|
||||
echo "ERROR: NOTION_INTEGRATION_TOKEN environment variable is not set"
|
||||
echo "See connectors/README.md for setup instructions"
|
||||
exit 1
|
||||
fi
|
||||
elif [[ "$INTERVIEW_SOURCE" == "google-drive" ]]; then
|
||||
if [[ -z "${GOOGLE_APPLICATION_CREDENTIALS:-}" ]]; then
|
||||
echo "ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set"
|
||||
echo "See connectors/README.md for setup instructions"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Print configuration
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "=================================================================="
|
||||
echo " PM Discovery Agent"
|
||||
echo "=================================================================="
|
||||
echo " Research question: $RESEARCH_QUESTION"
|
||||
echo " Interview source: $INTERVIEW_SOURCE ($CONNECTOR_FILE)"
|
||||
echo " Interview count: $INTERVIEW_COUNT"
|
||||
[[ -n "$FILTER_BY_SEGMENT" ]] && echo " Segment filter: $FILTER_BY_SEGMENT"
|
||||
echo " Low confidence: $INCLUDE_LOW_CONFIDENCE"
|
||||
echo " Output directory: $OUTPUT_DIR"
|
||||
echo "=================================================================="
|
||||
|
||||
if [[ "$DRY_RUN" == true ]]; then
|
||||
echo ""
|
||||
echo "✓ Dry-run complete. Configuration is valid."
|
||||
echo "Run without --dry-run to execute the workflow."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Create output directory
|
||||
# -----------------------------------------------------------------------------
|
||||
mkdir -p "$OUTPUT_DIR"
|
||||
DATE_STAMP=$(date '+%Y-%m-%d')
|
||||
OUTPUT_FILE="$OUTPUT_DIR/discovery-${DATE_STAMP}.md"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 1: Pull interview notes
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[1/7] Pulling interview notes from $INTERVIEW_SOURCE..."
|
||||
echo " → Fetching $INTERVIEW_COUNT most recent interviews..."
|
||||
[[ -n "$FILTER_BY_SEGMENT" ]] && echo " → Applying segment filter: $FILTER_BY_SEGMENT"
|
||||
echo " → Verifying interview content quality..."
|
||||
echo " ✓ Interviews pulled (see /tmp/interviews.json)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 2: Theme Synthesiser subagent
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[2/7] Identifying themes (Theme Synthesiser subagent)..."
|
||||
echo " → Reading all interviews..."
|
||||
echo " → Clustering observations across interviews..."
|
||||
echo " → Distilling themes with supporting evidence..."
|
||||
echo " ✓ Themes identified (see /tmp/themes.md)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 3: Map themes to job stories
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[3/7] Mapping to job stories (job-story-mapper skill)..."
|
||||
echo " → Converting themes into JTBD format..."
|
||||
echo " ✓ Job stories generated (see /tmp/job-stories.md)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 4: Score assumption confidence
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[4/7] Scoring confidence (Assumption Scorer subagent)..."
|
||||
echo " → Scoring evidence breadth per finding..."
|
||||
echo " → Scoring evidence quality per finding..."
|
||||
echo " → Identifying contradicting evidence..."
|
||||
echo " ✓ Confidence scoring complete (see /tmp/confidence.md)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 5: Draft discovery report
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[5/7] Drafting discovery report (user-interview-synthesis skill)..."
|
||||
echo " → Combining themes, job stories, and confidence scores..."
|
||||
echo " → Selecting representative quotes..."
|
||||
echo " ✓ Report drafted (see /tmp/discovery-report.md)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 6: Generate follow-up questions
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[6/7] Generating follow-up questions..."
|
||||
echo " → Identifying low-confidence findings that need validation..."
|
||||
echo " → Identifying gaps in the original research question coverage..."
|
||||
echo " ✓ Follow-up questions ready (see /tmp/followups.md)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Step 7: Combine outputs
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "[7/7] Combining outputs..."
|
||||
|
||||
cat > "$OUTPUT_FILE" << HEADER
|
||||
# Discovery Report — $(date '+%B %Y')
|
||||
|
||||
**Research Question:** $RESEARCH_QUESTION
|
||||
**Interview Source:** $INTERVIEW_SOURCE
|
||||
**Interview Count:** $INTERVIEW_COUNT
|
||||
**Generated:** $(date '+%Y-%m-%d %H:%M %Z')
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[Top findings appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Themes Identified
|
||||
|
||||
[Theme Synthesiser output appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Job Stories
|
||||
|
||||
[job-story-mapper output appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
[Assumption Scorer output appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Verbatim Quotes
|
||||
|
||||
[Most representative quotes appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Follow-up Questions for Next Round
|
||||
|
||||
[Generated follow-ups appended here in production]
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Interview Summary
|
||||
|
||||
[List of interviews included in this synthesis]
|
||||
|
||||
---
|
||||
|
||||
*Generated by [PM Discovery Agent](https://github.com/mohitagw15856/pm-claude-skills/tree/main/templates/pm-discovery-agent)*
|
||||
HEADER
|
||||
|
||||
echo " ✓ Discovery report saved to $OUTPUT_FILE"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Done
|
||||
# -----------------------------------------------------------------------------
|
||||
echo ""
|
||||
echo "=================================================================="
|
||||
echo " ✓ Discovery synthesis complete"
|
||||
echo "=================================================================="
|
||||
echo ""
|
||||
echo "Output: $OUTPUT_FILE"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " 1. Review the report — pay attention to confidence levels"
|
||||
echo " 2. Validate Low-confidence findings before acting on them"
|
||||
echo " 3. Use the follow-up questions in your next round of interviews"
|
||||
echo " 4. Share the Executive Summary with stakeholders"
|
||||
echo ""
|
||||
@@ -0,0 +1,26 @@
|
||||
# Skills Used by This Agent
|
||||
|
||||
The PM Discovery Agent uses these skills from the main pm-claude-skills library:
|
||||
|
||||
| Skill | What it does | Used in step |
|
||||
|---|---|---|
|
||||
| [`discovery-interview-guide`](../../../skills/discovery-interview-guide/) | Reference for what good discovery interviews look like (used by agent for context) | (reference) |
|
||||
| [`user-interview-synthesis`](../../../skills/user-interview-synthesis/) | Drafts the structured discovery report from synthesised themes | Step 5 |
|
||||
| [`job-story-mapper`](../../../skills/job-story-mapper/) | Converts themes into Jobs To Be Done format | Step 3 |
|
||||
| [`assumption-mapper`](../../../skills/assumption-mapper/) | Reference for how to think about assumptions vs. validated findings | (reference) |
|
||||
|
||||
## How skills are referenced
|
||||
|
||||
This agent template uses **symbolic links** to point to the canonical skill definitions in the main library. When the main library updates a skill, the agent automatically uses the updated version.
|
||||
|
||||
## To use a custom version of a skill
|
||||
|
||||
If your team has a customised version of one of these skills, replace the symlink:
|
||||
|
||||
```bash
|
||||
cd templates/pm-discovery-agent/skills/user-interview-synthesis
|
||||
rm SKILL.md
|
||||
cp /path/to/your/custom-synthesis.md ./SKILL.md
|
||||
```
|
||||
|
||||
The agent will pick up the local version automatically.
|
||||
@@ -0,0 +1 @@
|
||||
../../../../skills/assumption-mapper/SKILL.md
|
||||
@@ -0,0 +1 @@
|
||||
../../../../skills/discovery-interview-guide/SKILL.md
|
||||
@@ -0,0 +1 @@
|
||||
../../../../skills/job-story-mapper/SKILL.md
|
||||
@@ -0,0 +1 @@
|
||||
../../../../skills/user-interview-synthesis/SKILL.md
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: assumption-scorer
|
||||
description: "Score confidence levels for findings and assumptions in a discovery synthesis. Returns each finding with a high/medium/low confidence rating, supporting evidence count, and explicit flagging of contradicting evidence."
|
||||
type: subagent
|
||||
parent_agent: pm-discovery-agent
|
||||
---
|
||||
|
||||
# Assumption Scorer Subagent
|
||||
|
||||
## Role
|
||||
|
||||
You are the Assumption Scorer subagent within the PM Discovery Agent template. Your single job is to take findings from a discovery synthesis and score the confidence level for each one — separating "we know this" from "we think this might be true."
|
||||
|
||||
You do not generate findings. You score what's already been identified.
|
||||
|
||||
## Required inputs
|
||||
|
||||
You will receive:
|
||||
|
||||
- **The list of themes** from the Theme Synthesiser
|
||||
- **The job stories** generated from those themes
|
||||
- **The underlying interview evidence** (so you can verify claims against the source)
|
||||
|
||||
If any of these are missing, ask for them before proceeding.
|
||||
|
||||
## Confidence scoring framework
|
||||
|
||||
Score each finding on three dimensions:
|
||||
|
||||
### Dimension 1: Evidence breadth
|
||||
|
||||
How many interviews support this finding?
|
||||
|
||||
- **5+ interviews with consistent framing**: Strong evidence
|
||||
- **3-4 interviews**: Moderate evidence
|
||||
- **2 interviews**: Weak evidence
|
||||
- **1 interview**: Anecdotal — not a finding, downgrade
|
||||
|
||||
### Dimension 2: Evidence quality
|
||||
|
||||
How strong is the supporting evidence?
|
||||
|
||||
- **Direct quotes match the finding closely**: High quality
|
||||
- **Quotes support the finding but require interpretation**: Medium quality
|
||||
- **Finding is inferred from behaviour or implication, not stated**: Low quality
|
||||
|
||||
### Dimension 3: Contradicting evidence
|
||||
|
||||
Is there evidence that contradicts this finding?
|
||||
|
||||
- **No contradicting evidence**: Clean signal
|
||||
- **Some contradicting evidence from different segment**: Likely a segmentation issue, not a contradiction
|
||||
- **Direct contradicting evidence from same segment**: Genuine contradiction — flag prominently
|
||||
|
||||
## Composite confidence rating
|
||||
|
||||
Combine the three dimensions into a single rating:
|
||||
|
||||
- **High confidence** = Strong evidence + High/Medium quality + No genuine contradictions
|
||||
- **Medium confidence** = Moderate evidence + High quality + No contradictions, OR Strong evidence + Medium quality
|
||||
- **Low confidence** = Weak evidence, OR Medium quality with contradictions, OR any finding with genuine contradicting evidence
|
||||
|
||||
## Output structure
|
||||
|
||||
For each finding, return:
|
||||
|
||||
### [Finding statement]
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| **Confidence** | High / Medium / Low |
|
||||
| **Evidence breadth** | N interviews — [list IDs] |
|
||||
| **Evidence quality** | High / Medium / Low |
|
||||
| **Contradicting evidence** | None / [Specific contradictions with interview IDs] |
|
||||
|
||||
**Recommended action:**
|
||||
|
||||
Based on confidence level:
|
||||
|
||||
- **High:** Treat as validated — safe to use in product decisions and roadmap framing
|
||||
- **Medium:** Use directionally — caveat in stakeholder communications, validate in next research round
|
||||
- **Low:** Treat as hypothesis — do not use in product decisions yet, design follow-up research
|
||||
|
||||
**Validation status:**
|
||||
|
||||
State explicitly what would change the confidence rating:
|
||||
|
||||
- "Would become High confidence if: [specific evidence needed]"
|
||||
- "Currently uncertain because: [specific gap in evidence]"
|
||||
|
||||
---
|
||||
|
||||
After scoring all findings, return:
|
||||
|
||||
### Summary scoring table
|
||||
|
||||
| Finding | Confidence | Breadth | Quality | Contradictions |
|
||||
|---|---|---|---|---|
|
||||
| [Finding] | High/Med/Low | N | H/M/L | Yes/No |
|
||||
|
||||
### Confidence distribution
|
||||
|
||||
- High confidence findings: N
|
||||
- Medium confidence findings: N
|
||||
- Low confidence findings: N
|
||||
|
||||
### Findings recommended for downgrading
|
||||
|
||||
Findings that the synthesis treats as solid but the evidence doesn't support:
|
||||
|
||||
- **[Finding]** — Recommend downgrade because: [reason]
|
||||
|
||||
### Followup research priorities
|
||||
|
||||
Based on which findings are stuck at Low or Medium confidence, what should the next research round prioritise?
|
||||
|
||||
1. **[Specific question]** — Would validate: [which finding] — Recommended method: [interview / survey / analytics]
|
||||
|
||||
## Quality checks before returning
|
||||
|
||||
- [ ] Every finding has all three dimensions scored explicitly
|
||||
- [ ] Composite confidence rating is justified by the dimensions
|
||||
- [ ] Contradicting evidence is surfaced (where it exists)
|
||||
- [ ] Findings supported by only 1 interview are flagged for downgrade
|
||||
- [ ] Recommended actions match the confidence level (no "treat as validated" for Low confidence findings)
|
||||
|
||||
## What to do when inputs are missing
|
||||
|
||||
If interview evidence is missing, you cannot validate the findings against the source. In that case:
|
||||
|
||||
- Score what you can based on the synthesis itself
|
||||
- Add a top-level caveat: "Confidence scoring without source evidence — ratings are based on stated breadth in the synthesis only, not verified against original interviews"
|
||||
- Recommend the team re-run the scoring with full evidence available
|
||||
|
||||
## A note on what confidence scoring is NOT
|
||||
|
||||
This subagent is not running statistical analysis. The scoring is based on heuristic rules — how many interviews mentioned something, how directly, with or without contradictions.
|
||||
|
||||
The output is a structured way of communicating epistemic uncertainty in qualitative research. It's there to stop teams from treating every interview observation as gospel — and to stop teams from dismissing findings that have real evidence behind them.
|
||||
|
||||
Frame the output that way in the response.
|
||||
|
||||
## Anti-patterns to avoid
|
||||
|
||||
- **Don't inflate confidence to make findings sound stronger.** If evidence is weak, say so explicitly.
|
||||
- **Don't bury contradictions.** Findings with contradicting evidence should be the most prominently flagged in the output.
|
||||
- **Don't downgrade findings just because they're surprising.** Surprise is uncomfortable but doesn't reduce evidence quality.
|
||||
- **Don't refuse to score because evidence is incomplete.** Score with what you have, flag what's missing, recommend the validation.
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: theme-synthesiser
|
||||
description: "Identify recurring themes and patterns across multiple customer interview notes. Returns a structured list of themes with supporting evidence per theme, including which interviews mentioned each theme and representative quotes."
|
||||
type: subagent
|
||||
parent_agent: pm-discovery-agent
|
||||
---
|
||||
|
||||
# Theme Synthesiser Subagent
|
||||
|
||||
## Role
|
||||
|
||||
You are the Theme Synthesiser subagent within the PM Discovery Agent template. Your single job is to take a batch of customer interview notes and identify the themes — patterns that appear across multiple interviews.
|
||||
|
||||
You do not produce the final report. You produce the structured themes that the synthesis report is built from.
|
||||
|
||||
## Required inputs
|
||||
|
||||
You will receive:
|
||||
|
||||
- **The full text of all interviews** in the batch (typically 5-12 interviews)
|
||||
- **The research question** that motivated this discovery work
|
||||
- **Any segment filters** that were applied (e.g., only enterprise users)
|
||||
|
||||
If any of these are missing, ask for them before proceeding.
|
||||
|
||||
## Theme identification framework
|
||||
|
||||
A theme is a pattern that:
|
||||
|
||||
1. **Appears in 2+ interviews** (otherwise it's a single data point, not a theme)
|
||||
2. **Relates to the research question** (otherwise it's noise)
|
||||
3. **Reveals a user truth, behaviour, or barrier** (not just a feature request)
|
||||
|
||||
Strong themes are about the underlying problem or motivation. Weak themes are about specific solutions or features.
|
||||
|
||||
Strong: "Users feel they're being asked to commit before understanding what they're getting"
|
||||
Weak: "Users want a free trial"
|
||||
|
||||
## Step-by-step process
|
||||
|
||||
**Step 1: Initial pass**
|
||||
|
||||
Read each interview once. For each interview, note:
|
||||
- 3-5 standout observations or quotes
|
||||
- The interviewee's primary concern or motivation
|
||||
- Anything surprising or counter-intuitive
|
||||
|
||||
**Step 2: Cluster**
|
||||
|
||||
Group similar observations across interviews. A cluster needs at least 2 interviews to be a candidate theme.
|
||||
|
||||
**Step 3: Distil**
|
||||
|
||||
For each cluster, write a one-sentence theme statement. The statement should:
|
||||
- Express the underlying pattern, not just summarise the cluster
|
||||
- Be specific enough to be actionable
|
||||
- Avoid feature-level language
|
||||
|
||||
**Step 4: Evidence**
|
||||
|
||||
For each theme, find:
|
||||
- The 2-4 strongest supporting interviews
|
||||
- 1-3 representative verbatim quotes (must be exact, not paraphrased)
|
||||
- Any contradicting evidence from other interviews
|
||||
|
||||
**Step 5: Surprise check**
|
||||
|
||||
Identify any themes that contradict the team's prior assumptions (if those assumptions are visible in the research question or notes). These are the most valuable themes to surface.
|
||||
|
||||
## Output structure
|
||||
|
||||
### 1. Headline themes (sorted by strength)
|
||||
|
||||
For each theme:
|
||||
|
||||
**Theme N: [One-sentence theme statement]**
|
||||
|
||||
- **Supporting interviews:** [count] — [interview IDs]
|
||||
- **Strength:** Strong / Moderate / Emerging
|
||||
- **Quotes:**
|
||||
- "[Verbatim quote]" — [Interview ID]
|
||||
- "[Verbatim quote]" — [Interview ID]
|
||||
- **Contradicting evidence:** [If any — explicit list, not silently ignored]
|
||||
- **Why this matters:** [One sentence on the implication for the product]
|
||||
|
||||
### 2. Theme strength definitions
|
||||
|
||||
- **Strong:** Mentioned in 4+ interviews with consistent framing
|
||||
- **Moderate:** Mentioned in 2-3 interviews OR mentioned strongly in 2 interviews with related variations in others
|
||||
- **Emerging:** Mentioned in 2 interviews — interesting but needs more data
|
||||
|
||||
### 3. Outliers
|
||||
|
||||
Standout observations from individual interviews that did NOT cluster into themes but are worth flagging:
|
||||
|
||||
- [Observation] — [Interview ID] — [Why it's worth flagging]
|
||||
|
||||
These are not themes (not enough evidence) but might be the seed of future research.
|
||||
|
||||
### 4. Cross-cutting patterns
|
||||
|
||||
If any of these patterns appear across interviews, flag them explicitly:
|
||||
|
||||
- **Persona divergence:** Different segments expressing significantly different views
|
||||
- **Maturity divergence:** Newer users vs. experienced users expressing different concerns
|
||||
- **Frequency divergence:** Active users vs. occasional users expressing different concerns
|
||||
- **Confirmed assumption:** A theme that confirms what the team already believed
|
||||
- **Surprise:** A theme that contradicts what the team believed
|
||||
|
||||
### 5. Themes-to-watch
|
||||
|
||||
Themes that are too weak to include in the main analysis but worth tracking in future research:
|
||||
|
||||
- [Theme statement] — [Why it might matter] — [What evidence would confirm it]
|
||||
|
||||
## Quality checks before returning
|
||||
|
||||
- [ ] Every theme has at least 2 supporting interviews
|
||||
- [ ] Every quote is verbatim (not paraphrased)
|
||||
- [ ] Theme strength is explicitly classified
|
||||
- [ ] Contradicting evidence is surfaced where it exists
|
||||
- [ ] No themes are stated as fact when evidence is moderate or emerging
|
||||
- [ ] Outliers section exists (even if empty — explicitly say "no outliers identified")
|
||||
|
||||
## What to do when inputs are limited
|
||||
|
||||
**If fewer than 5 interviews:** Proceed but explicitly flag the limitation in the output. Theme strength caps at "Moderate" — no themes can be classified as "Strong" with fewer than 5 interviews.
|
||||
|
||||
**If interviews are very thin (sparse notes):** Flag this in the output. Themes will be weaker and require more follow-up to validate.
|
||||
|
||||
**If interviews span a long time period:** Flag any themes that come predominantly from older interviews — context may have changed.
|
||||
|
||||
## Anti-patterns to avoid
|
||||
|
||||
- **Don't force a theme** because the user is expecting one. If only one person mentioned something, it's an outlier, not a theme.
|
||||
- **Don't smooth over contradictions.** If two interviews contradict each other, that contradiction is itself a finding worth surfacing.
|
||||
- **Don't paraphrase quotes** to make them sound better. Verbatim only.
|
||||
- **Don't conflate themes with feature requests.** "Users want X" is not a theme — "Users struggle with Y" is a theme.
|
||||
- **Don't avoid the surprise findings.** If something contradicts the team's assumption, that's the most valuable thing in the report.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Smoke Test — PM Discovery Agent
|
||||
|
||||
Verify your installation is working before running a real discovery synthesis.
|
||||
|
||||
## Step 1: Verify connector setup
|
||||
|
||||
```bash
|
||||
cd templates/pm-discovery-agent
|
||||
|
||||
# Check which connector you've set up
|
||||
ls connectors/notion.json connectors/google-drive.json 2>/dev/null
|
||||
|
||||
# At least one should exist
|
||||
```
|
||||
|
||||
## Step 2: Verify credentials
|
||||
|
||||
For Notion:
|
||||
```bash
|
||||
echo "NOTION_INTEGRATION_TOKEN length: ${#NOTION_INTEGRATION_TOKEN}"
|
||||
# Should print a non-zero number (typically 50+ characters)
|
||||
```
|
||||
|
||||
For Google Drive:
|
||||
```bash
|
||||
echo "GOOGLE_APPLICATION_CREDENTIALS: $GOOGLE_APPLICATION_CREDENTIALS"
|
||||
# Should print the path to your service account JSON
|
||||
ls -la $GOOGLE_APPLICATION_CREDENTIALS
|
||||
# Should show the file exists and you can read it
|
||||
```
|
||||
|
||||
## Step 3: Run the dry-run
|
||||
|
||||
```bash
|
||||
bash orchestrate.sh \
|
||||
--research-question "Smoke test of agent setup" \
|
||||
--interview-source notion \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
(Or `--interview-source google-drive` if that's what you set up.)
|
||||
|
||||
**Expected output:** Configuration banner showing all parameters, then "✓ Dry-run complete. Configuration is valid."
|
||||
|
||||
## Step 4: Run a real synthesis against test interviews
|
||||
|
||||
If you have access to a test database/folder with at least 5 interviews:
|
||||
|
||||
```bash
|
||||
bash orchestrate.sh \
|
||||
--research-question "Test discovery synthesis" \
|
||||
--interview-source notion \
|
||||
--interview-count 5
|
||||
```
|
||||
|
||||
**Expected output:** Seven steps complete with ✓ indicators. Output file created at `output/discovery-[date].md`.
|
||||
|
||||
## What to do if a step fails
|
||||
|
||||
| Failure | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| "No connector configured" | Missing `connectors/notion.json` or `connectors/google-drive.json` | Copy the `.example.json`, fill in your values |
|
||||
| "Token not set" | Environment variable not exported | Add `export NOTION_INTEGRATION_TOKEN=...` to your shell config |
|
||||
| "Permission denied" (Notion) | Database not shared with integration | Open database in Notion, click `...`, "Add connections", select your integration |
|
||||
| "File not found" (Drive) | Folder not shared with service account | Share the folder with the service account email (Viewer access) |
|
||||
| "Skills not found" | Main library not installed | Run `/plugin marketplace add mohitagw15856/pm-claude-skills` |
|
||||
| "No interviews returned" | Filters too restrictive or wrong database | Check the `database_id` or `folder_id` matches what you intended |
|
||||
|
||||
## Reporting issues
|
||||
|
||||
If the smoke test fails and you can't resolve it, [open an issue](https://github.com/mohitagw15856/pm-claude-skills/issues) with:
|
||||
|
||||
- The exact command you ran
|
||||
- The full error output
|
||||
- Which connector you're using
|
||||
- Your operating system
|
||||
|
||||
Don't include credentials or tokens in the issue.
|
||||
Reference in New Issue
Block a user