borghei/Claude-Skills / project-management/discovery/interview-synthesis
interview-synthesis
VerifiedTurns customer interview notes into evidenced themes, an opportunity tree and follow-up questions. Use when you have just run interviews, need to show what customers said, or must find evidence gaps before the next round.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.9 KB |
| assets/interview_input_template.json | config | 1.8 KB |
| assets/opportunity_tree_template.md | markdown | 2.4 KB |
| examples/wayfinder-8-interview-synthesis.md | markdown | 15.1 KB |
| references/red-flags.md | markdown | 13.1 KB |
| references/synthesis-framework-and-tooling.md | markdown | 7.6 KB |
| references/synthesis-methodology-guide.md | markdown | 8.1 KB |
| scripts/interview_synthesizer.pyexecutable | script | 25.0 KB |
references/synthesis-framework-and-tooling.md
View on GitHub# Synthesis Framework, Workflow & Tooling
> Read this when you need the full 5-step synthesis framework (snippet extraction → coding → theme clustering → opportunity solution tree → follow-ups), the end-to-end workflow, the `interview_synthesizer.py` flag reference, troubleshooting, or success criteria.
## Synthesis Framework
The framework moves from raw transcript -> coded snippets -> themes -> opportunities -> solutions, with explicit evidence trails at each step.
### Step 1: Snippet Extraction (Portigal)
For each interview, extract atomic snippets. A snippet is a single quote or paraphrase that captures one of:
- **A story** -- A specific past event with context, action, and outcome ("Last Tuesday I tried to..."). Stories are the highest-evidence data.
- **A contradiction** -- The participant says X but their behavior shows Y. Contradictions reveal latent needs.
- **A surprise** -- Something the interviewer did not expect. Surprises mark the edge of the team's mental model.
- **An emotion** -- Frustration, delight, fear, relief. Emotional markers signal motivation strength.
Avoid extracting opinions about hypothetical futures ("I would use X if...") -- they are low-evidence.
### Step 2: Coding into Categories
Each snippet is coded with:
- **Need code** -- What underlying need does this point to? (e.g., "trust-in-data", "time-to-insight", "control-over-process")
- **Job code** -- What job-to-be-done is the participant trying to accomplish? Use the Klement format: *When [situation], I want to [motivation], so I can [outcome].*
- **Pain code** -- What specific friction, risk, or workaround appears? (e.g., "manual-reconciliation", "fear-of-data-loss")
- **Gain code** -- What positive outcome would matter? (e.g., "faster-close", "audit-trail", "peer-recognition")
- **Strength** -- 1 (single mention), 2 (multiple participants), 3 (multiple participants + behavioral evidence)
### Step 3: Theme Clustering
Group coded snippets into themes. A theme requires:
- At least 3 snippets
- From at least 2 different participants
- Sharing a coherent need, job, pain, or gain code
For each theme, write a 1-sentence headline that a stakeholder can scan in 5 seconds. Example: *"Finance leads do not trust automated reconciliations because they cannot see the rule that produced each match."*
### Step 4: Opportunity Solution Tree (Torres)
Build a tree with four levels:
```
Outcome (top)
|
+-- Opportunity 1 (a customer need, pain, or desire)
| +-- Solution A
| +-- Solution B
| +-- Solution C
|
+-- Opportunity 2
+-- Solution D
+-- Solution E
```
**Rules:**
- The outcome at the top is a measurable business or user outcome -- not a feature.
- Opportunities are customer-side framings ("Finance leads cannot verify automation rules"), not solution-side ("Add a rules dashboard").
- Each opportunity must trace to >=1 themed insight.
- Solutions live under opportunities so the team can compare multiple solutions against the same opportunity.
### Step 5: Follow-Up Question Generation
For each weak-evidence theme (strength <= 2) or unmapped assumption, generate 2-3 targeted follow-up questions for the next round of interviews. Good follow-ups:
- Ask for stories, not opinions ("Tell me about the last time..." not "Would you...").
- Probe contradictions ("You mentioned X earlier but also Y -- can you walk me through that?").
- Test counterfactuals ("If [workaround] disappeared tomorrow, what would you do?").
## Workflow
1. **Prepare input.** Convert interview notes into JSON with one entry per interview containing participant id, role, and a list of question/answer pairs. See `assets/interview_input_template.json`.
2. **Run the synthesizer.** `python scripts/interview_synthesizer.py --input interviews.json --format markdown --output synthesis.md`. Use `--format mermaid` for the opportunity solution tree alone.
3. **Review themes.** Validate each theme against the source snippets. Drop themes that fail the 3-snippet / 2-participant threshold.
4. **Refine the tree.** Edit the generated tree in `assets/opportunity_tree_template.md`. Add or split opportunities based on stakeholder review.
5. **Plan follow-ups.** Use the generated follow-up list to script the next interview round.
6. **Hand off.** Feed validated opportunities into `discovery/brainstorm-experiments/` for hypothesis design, or directly into `execution/create-prd/` if evidence is strong enough.
## Tools
| Tool | Purpose | Command |
|------|---------|---------|
| `interview_synthesizer.py` | Cluster snippets into themes, build opportunity solution tree, generate follow-up questions | `python scripts/interview_synthesizer.py --input interviews.json --format markdown --output synthesis.md` |
The tool supports all six PM-standard output formats (`json`, `markdown`, `mermaid`, `confluence`, `notion`, `linear`) per `SHARED_OUTPUT_SCHEMA.md`. Use `--demo` to generate a sample output for any format.
## Troubleshooting
| Symptom | Likely Cause | Resolution |
|---------|-------------|------------|
| Themes feel generic or obvious | Snippet extraction captured opinions, not stories | Re-extract using the story/contradiction/surprise/emotion filter; drop hypothetical-future quotes |
| Opportunity tree has too many top-level opportunities (>7) | Outcome at the top is too broad | Narrow the outcome (e.g., "Increase activation" -> "Reduce time from signup to first successful import") |
| Solutions appear instead of opportunities | Team jumped to solution mode during synthesis | Rewrite each opportunity as a customer-side framing; move every "Add X feature" line into the Solutions row |
| Only 1-2 themes emerge from 10+ interviews | Coding categories too narrow OR participants too homogenous | Broaden need codes to capture latent jobs; check that participants span at least 2 segments |
| Follow-up questions are leading or close-ended | Questions phrased as solution validation | Convert each follow-up to a "Tell me about the last time you..." story-prompt |
| Mermaid tree renders flat in Confluence | Confluence requires the Mermaid macro to be enabled | Use `--format confluence` which converts the tree to a nested bullet list |
| `--input` JSON parse error | Interview file missing required fields (`participant`, `qa`) | Validate against `assets/interview_input_template.json`; run `python -m json.tool interviews.json` |
## Success Criteria
- Every theme references >=3 snippets from >=2 participants
- Opportunity tree has 1 measurable outcome at the top, 3-7 opportunities, and >=1 solution per opportunity
- Each opportunity traces back to >=1 themed insight (evidence trail intact)
- Follow-up questions are story-prompts, not opinion-prompts
- Synthesis produced within 5 working days of the last interview (before insights decay)
- Stakeholders can read the executive summary in under 3 minutes and name the top 3 opportunities
## Tool Reference
### interview_synthesizer.py
Ingests interview JSON and produces themed clusters, an opportunity solution tree, and a follow-up question list.
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--input` | string | (required unless `--demo`) | Path to interview JSON file (see `assets/interview_input_template.json`) |
| `--format` | string | `markdown` | Output format: `json`, `markdown`, `mermaid`, `confluence`, `notion`, `linear` |
| `--output` | string | stdout | Output file path; if omitted, prints to stdout |
| `--outcome` | string | "Improve customer outcome" | Top-of-tree outcome label |
| `--min-strength` | int | 1 | Drop themes below this evidence strength (1-3) |
| `--demo` | flag | off | Generate sample synthesis using a built-in fixture |
**Mermaid diagram type:** `graph LR` (opportunity solution tree).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |