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.

  • Product Management
  • $user-research-synthesis
  • 150 lines
  • 2 files
  • ~1,500 tokens
  • MIT
  • Updated

Install

curl -fsSL codexskills.dev/install.sh \  | sh -s -- user-research-synthesis

Installs to ~/.agents/skills/user-research-synthesis/ for every project on this machine.

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

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.

~/.agents/skills/user-research-synthesis/SKILL.md

--- name: user-research-synthesis description: Synthesizes qualitative user research - interview transcripts, usability sessions, open-ended survey answers, support conversations - into… license: MIT ---

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

  1. Collect sources: transcripts, interview snapshots, usability notes, survey exports, ticket exports. Note the research questions and decision they were meant to inform.
  2. Assign each participant a code (P1…Pn) with segment attributes (role, plan, tenure, churned or active). Remove names and contact details from working files.
  3. Keep raw data where the organization’s policy says. Do not commit identifiable transcripts to a repository or paste them into external tools.
  4. 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:

FieldMeaning
SupportNumber of distinct participants with at least one note in the theme
ContradictParticipants whose evidence goes the other way
SegmentsWhich segments it appears in
StrengthBehaviour 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.yamlgenerated from this page

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.

esc