User Research Synthesis skill for Codex
Insights traceable to the people who said them. Codex breaks transcripts, usability notes and survey comments into anonymized atomic observations, clusters them by meaning rather than by interview question, and counts distinct participants supporting and contradicting each theme. Insights separate observation from interpretation, carry a confidence level and an implication, and the report maps answers back to the original research questions and names who was not heard.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- user-research-synthesis Installs to ~/.agents/skills/user-research-synthesis/ for every project on this machine.
curl -fsSL codexskills.dev/cli.mjs -o codex-skills.mjsnode codex-skills.mjs install user-research-synthesis The CLI also searches, updates and removes skills. Run it with no arguments to pick from a list. Needs Node 20.12+.
curl -fsSL codexskills.dev/install.sh \ | sh -s -- --project user-research-synthesis Installs to .agents/skills/user-research-synthesis/ in the current repository. Commit it and everyone who runs Codex there gets it.
curl -fsSLO codexskills.dev/downloads/user-research-synthesis.zipunzip -o user-research-synthesis.zip -d ~/.agents/skills/ The archive holds the skill folder with its generated agents/openai.yaml. Unzip into .agents/skills/ to scope it to a repo.
& ([scriptblock]::Create((irm codexskills.dev/install.ps1))) user-research-synthesis PowerShell 5.1 or 7. Installs to %USERPROFILE%\.agents\skills\. Add -Project for the current repo.
104-line POSIX script. No sudo, no telemetry. Read install.sh
Use it in Codex
Start a prompt with $user-research-synthesis, or pick it from /skills.
You can also just describe the task: Codex reads the description below and loads the playbook when your request matches.
What Codex reads before loading it
Synthesizes qualitative user research - interview transcripts, usability sessions, open-ended survey answers, support conversations - into evidence-backed insights through atomic observations, affinity mapping, theme counts across participants, insight statements with implications, and an insight report that separates what was observed from what is inferred. Use when asked to synthesize interviews, do affinity mapping, find themes in research notes or survey comments, write a research findings report, or turn research into product recommendations.
Use it when
- Interviews or usability sessions are done and need synthesis
- Hundreds of open-ended survey or support comments need coding
- Stakeholders need a findings report with evidence they can audit
- Research needs to be turned into product implications
Use something else when
- You are still planning or running the interviews: use customer-interviews
- You are combining many research sources into a strategic decision: use research-synthesis
- The input is a stream of feature requests to route and rank: use feedback-triage
How to check the result
Three random insights trace back to specific notes and participants, counts are distinct people, and every research question has an answer or an explicit gap.
The mistake it prevents
Clustering notes by the interview question that produced them, which reproduces the guide instead of revealing users' own patterns.
Synthesis is done well when every insight can be traced back to specific participants and quotes, the report says how many people support and contradict each theme, observed facts are kept apart from interpretation, and each insight ends in an implication a team can act on.
Inputs and preparation
- Collect sources: transcripts, interview snapshots, usability notes, survey exports, ticket exports. Note the research questions and decision they were meant to inform.
- Assign each participant a code (P1…Pn) with segment attributes (role, plan, tenure, churned or active). Remove names and contact details from working files.
- Keep raw data where the organization’s policy says. Do not commit identifiable transcripts to a repository or paste them into external tools.
- Check coverage: which segments are represented, and which are missing? Missing segments are a limitation in the report, not something to extrapolate.
Step 1: atomic observations
Break every source into atomic notes: one observation per note, with source and location. Do not cluster yet.
[P3 12:40] Rebuilds the weekly plan from scratch whenever someone is out sick
[P3 14:05] "I don't trust the numbers until I've checked them in the spreadsheet"
[P7 08:15] Exports to CSV every Friday to send the client a status report
[S112] Survey: "too many clicks to reassign a task" (plan: Team, tenure 3 months)
Types to tag: behaviour, pain, goal, workaround, quote, context,
reaction (to a concept). Behaviours and workarounds outweigh opinions.
For more than ~300 notes, process source by source, then merge, so context windows stay manageable and no source gets skimmed.
Step 2: affinity mapping
- Cluster notes bottom-up by similarity of meaning, not by the interview question that produced them or by product area.
- Name each cluster with a sentence that says something (“People re-verify numbers in spreadsheets before sharing them”), not a label (“Trust”).
- Split clusters over ~15 notes; merge clusters under 3 notes or mark them as weak signals.
- Group clusters into 4-8 higher-level themes.
Step 3: count and test
For each theme record:
| Field | Meaning |
|---|---|
| Support | Number of distinct participants with at least one note in the theme |
| Contradict | Participants whose evidence goes the other way |
| Segments | Which segments it appears in |
| Strength | Behaviour observed vs only stated |
Count participants, not notes; one talkative participant can fill a cluster alone. State frequencies as “7 of 12 participants”, never as percentages for small samples.
Check alternative explanations: is the theme caused by one segment, one interviewer’s questions, or the recruiting channel?
Step 4: insight statements
An insight combines observation, the reason behind it, and why it matters:
Insight: Ops leads re-check plan numbers in spreadsheets before sharing them with
clients (7 of 12; strongest among agencies with client-billed hours) because a wrong
number in front of a client damages their credibility. Our reports are exported and
re-formatted every week, so the in-product report is not trusted as the final source.
Implication: Make reports trustworthy enough to send as-is (show data freshness and
source), before adding new report types.
Confidence: medium-high (observed behaviour in 5 sessions, stated by 2 more)
Separate clearly:
- Observed: what people did or said (with references).
- Interpreted: why you think they did it.
- Recommended: what the team might do. Recommendations are hypotheses to test, not findings.
Workflow
- [ ] 1. Gather sources, research questions, participant table; anonymize
- [ ] 2. Extract atomic, tagged observations per source
- [ ] 3. Affinity-map into named clusters, then themes
- [ ] 4. Count supporting and contradicting participants per theme
- [ ] 5. Write insight statements with implications and confidence
- [ ] 6. Map insights back to the original research questions
- [ ] 7. Write the report; list limitations and open questions
Report template
# Research findings: <topic>
Decision this informs: <...> | Method: 12 interviews + 340 survey comments | Dates: <...>
Participants: <table of codes, segment attributes>
## Summary (5 bullets max)
## Insights
### 1. <insight sentence>
Evidence: 7 of 12 participants (P1, P3, P4, P7, P9, P10, P12); contradicted by P5
Quotes: "<verbatim>" - P3, ops lead, agency
Implication: <...> | Confidence: <low/medium/high and why>
## Answers to research questions
| Question | Answer | Insights |
## Surprises and weak signals
## Limitations (who we did not hear from, biases in recruiting)
## Recommended next steps (hypotheses to test)
## Appendix: cluster list with note counts
Open-ended survey answers at scale
For hundreds of comments: read a random sample of ~50 first and draft a codebook (code name, definition, example). Apply it to all comments, allowing multiple codes per comment, then count. Re-read 10% of coded comments to check consistency, and refine codes that were applied inconsistently. Report counts with the codebook so others can audit them.
Gotchas
- Clustering by interview question reproduces your guide, not the users’ reality.
- Quotes chosen because they are vivid can overstate rare views; pair each quote with its theme count.
- Feature requests are data about a need, not the need itself; synthesize the underlying problem.
- Synthesis by one person is biased by that person; ask a teammate to re-cluster a sample if stakes are high.
- Do not mix usability findings (can they use it) with value findings (do they want it) in one theme.
Verification
Pick three insights at random and trace each back to its notes and sources; every claim must be supported. Confirm counts are distinct participants, each theme lists contradicting evidence (or “none found”), each research question has an answer or an explicit “not answered”, and limitations name the missing segments.
What the zip contains
SKILL.md plus the interface file below. Nothing runs on install.
agents/openai.yaml
Gives the Codex app a display name, a one-line description and a starter prompt for this skill.
interface:
display_name: "User Research Synthesis"
short_description: "Insights traceable to the people who said them"
default_prompt: "$user-research-synthesis Synthesize these 12 interview transcripts into themes and insights" About this skill
Written and maintained by the Codex Skills editors to the same editorial standard as every skill here: a selective description, a real workflow, known pitfalls and a way to verify the work. First published , last updated . MIT licensed. Something wrong or out of date? Tell us.