Skip to main content
command CX Codex

ux-research — Claude Code command: what it does, how to install

ux-research plans user research studies, drafts interview guides and surveys, and synthesizes raw field notes into product decisions.

MIT ★ 110 updated 2026-11-02

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill
Open on GitHub

What ux-research does

The /ux-research command belongs to the ux plugin. It structures research planning around clear product decisions. During planning mode, it categorizes research questions into problem discovery, validation, or usability tests. Then it generates ready deliverables, including screener surveys, task-based usability protocols, and interview scripts with behavioral questioning.

The command forbids hypothetical questions like asking respondents whether they would buy something. Everything is anchored to past actions. Once fieldwork finishes, running the command with --synthesize delegates raw transcripts or survey CSV files to a background task. Key findings and study metadata are saved to .ux/last-research.json.

What it helps with

  • draft interview guides focused on past user behavior
  • generate unbiased surveys with randomized answer options
  • calculate sample sizes and incentives for participant recruiting
  • turn raw interview transcripts into decision-ready findings

Example prompts for the agent

  • /ux-research plan a usability study for the checkout flow, budget 8 sessions at 45 minutes
  • /ux-research create an interview script for problem discovery around team onboarding
  • /ux-research --synthesize notes.txt, original question: what blocks daily adoption

How to install ux-research

1Plugin marketplace

/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill

2Manually: put the files in place

.claude/commands/ux-research.md

Call it with /ux-research. For all projects use ~/.claude/commands/

Questions about ux-research

How to install ux-research in Claude Code?

Add the marketplace source with /plugin marketplace add Laith0003/ux-skill, then run /plugin install ux@ux-skill.

What does ux-research do?

It chooses an appropriate research method, writes complete study artifacts like interview scripts or screeners, and produces recruitment guidelines.

When should you pass the --synthesize flag?

Use /ux-research --synthesize when data collection is complete and you have transcripts, notes, or survey CSV files ready for pattern extraction.

Source text

ux-research.md · MIT
---
description: User research planning — interview scripts, survey design, recruitment screener, synthesis. Triggers on "plan a research study", "I need interview questions", "design a survey", "how do I recruit users". Use when planning user research, writing interview scripts, designing a survey, creating a screener, scoping recruitment, synthesizing research data into recommendations. Skip when the user already has research data and wants synthesis (use ux-research --synthesize), the answer is already known with high confidence, low-risk reversible decisions, backend or infrastructure work.
allowed-tools: Read, Write, Edit, Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(mkdir:*), Glob, Grep, Task
disable-model-invocation: false
---

# /ux-research

You are running the `/ux-research` command from the `ux` plugin. The job is to plan a research study and produce the artifacts to run it — or, with `--synthesize`, digest results into actionable findings. Methodologically rigorous, anti-bias by default.

## When to use

Triggers: "plan a research study", "I need interview questions", "design a survey", "how do I recruit users", "user testing plan", "diary study", "preference test", "fake door", "smoke test", "synthesize my interview notes". Also runs as a sub-step of `/ux-workshop` between phases.

## Input

Required (planning mode):
- **Research question(s)**: what you want to learn, in plain language
- **Design decision the research informs**: the action that will change based on findings
- **Budget / timeline**: minutes per session, total sessions, dollars

Required (synthesis mode, triggered by `--synthesize`):
- Path to raw notes / transcripts / survey CSV
- The original research question(s) for grounding

If anything's missing, ask once: *"Research question, the design decision it informs, and budget/timeline (sessions × minutes × incentive)?"*

## Process (planning mode)

### 1. Frame the research question

Classify the question into one of:
- **Problem discovery** — is there a problem worth solving here?
- **Solution validation** — does our proposed solution address the problem?
- **Usability testing** — can users actually use what we built?
- **Preference / desirability** — which option resonates?
- **Segmentation** — who are the user types and what differentiates them?

A research question that fits two categories is too broad. Split it.

### 2. Pick the method

| Question type | Default method | Alternative |
|---|---|---|
| Problem discovery | Semi-structured interview (n=5-8) | Diary study (n=5, 1 week) |
| Solution validation | Concept test (n=5-8) + structured interview | Fake door (n=∞ via traffic) |
| Usability testing | Moderated task-based test (n=5-8) | Unmoderated remote (n=15+) |
| Preference / desirability | Within-subjects preference test (n=8-12) | A/B test (n=large, traffic-dependent) |
| Segmentation | Survey (n=100+) | Card sort + cluster analysis (n=15-25) |

Smoke tests and fake doors are valid for binary problem-existence checks before deeper qual work.

### 3. Generate the artifact

Build the deliverable for the chosen method:

- **Interview script** — open-ended + behavior-focused questions, no leading wording. Structure: warm-up (2-3 q), context (current behavior), specific (past experience with the problem), reflection (what would solve this), wrap-up. Never ask "would you use" — ask about past behavior.
- **Survey** — anti-bias structure. Randomize answer order. Mix 5-point Likert with open-ended. Screen out professionals/insiders. Attention check question.
- **Usability test plan** — tasks framed as goals not steps. Time-box per task. Define success criteria upfront. Think-aloud protocol stated to participant.
- **Diary study brief** — daily prompt, max 5 min effort, end-of-study debrief interview.
- **Screener questionnaire** — disqualifying criteria first, then qualifying. Stated incentive, time commitment, schedule.

### 4. Recruitment plan

- **Where**: user pool / customer list / Respondent.io / UserInterviews / Prolific / community forums / DM intercept on the product / partner contacts
- **Incentive**: dollar value matched to time (industry rule of thumb: ~$1-2/minute for B2C, $3-6/minute for B2B / experts)
- **Volume**: target sample + 30% buffer for no-shows

### 5. Analysis plan

State upfront how findings will be synthesized:
- Affinity mapping for interviews
- Cross-tabs + chi-square for surveys
- Task completion + time-on-task + System Usability Scale (SUS) for usability
- Tag taxonomy for diary studies

## Process (synthesis mode)

Dispatch `research-synthesizer` via Task. Pass:
- Raw input files
- Original research question
- Method that was used
- Instruction to produce: themes (with supporting quotes), behavioral patterns, surprises, decision-ready insights (each tied back to the original design decision), recommended next steps

### Output format

```
─── research plan ───
Question:   <verbatim>
Decision:   <what changes based on findings>
Method:     <method>
Sample:     n=<target> (n=<target+buffer> recruited)
Timeline:   <weeks>
Budget:     $<total>

─── artifact ───
<the deliverable — interview script / survey / test plan / screener — in full>

─── recruitment ───
Source:     <where>
Incentive:  $<amount> / <duration>
Screener:   <key criteria>

─── analysis plan ───
<how findings will be synthesized>

─── next ───
Run the study, then come back with /ux-research --synthesize
```

### State

Write to `.ux/last-research.json`:

```json
{
  "command": "ux-research",
  "timestamp": "<ISO8601>",
  "mode": "planning|synthesis",
  "question": "<verbatim>",
  "decision": "<design decision>",
  "method": "<method>",
  "sample_target": <n>,
  "incentive": "<amount>",
  "artifact_file": "<path>",
  "synthesis_findings": ["<key themes>"]
}
```

## Hard rules

- Never ask "would you use" — ask about past behavior. Stated intent is a noise channel.
- Never recommend n<5 for qual; never recommend n<30 for quant; never recommend n<100 for segmentation surveys.
- Screen out product professionals (designers, PMs, UXers) unless they ARE the target user.
- Randomize answer order in surveys. No order-bias artifacts.
- Attention check questions on every survey.
- Time-box every session. Sessions that run long produce diminishing returns and respondent fatigue.
- Tie every finding back to the original research question. Findings that don't map are notes, not insights.

## Failure modes

- **Multi-question studies**: trying to learn 5 things in one session = learning 0 things well. Split the study.
- **Leading wording**: "How much do you love X?" — reject and rewrite.
- **Recruiting from product users only**: confirmation bias. Mix in non-users for discovery work.
- **No incentive**: response rate craters. Always pay participants.
- **Synthesis as a quote dump**: themes need to be patterns across participants, not "one person said X."

## Error Handling

| Error condition | Recovery |
|---|---|
| No research budget specified | Ask: "Sessions × minutes × incentive — what's the budget?" |
| Conflicting research goals (study tries to learn 3+ things) | List the goals, ask the user to pick the primary one; offer to split into separate studies |
| Recruitment channel unclear | Propose channels matched to the audience (Respondent.io / UserInterviews / Prolific / customer list / community / DM intercept) |
| Synthesis mode: raw input files missing or unreadable | Ask for the file path or pasted transcript; stop until provided |
| Sample size requested below floor (n<5 qual, n<30 quant) | Refuse and explain the floor; offer the minimum viable design |
| Voice/leading wording in interview script | Rewrite and flag the bias risk before delivery |

For path issues: see references/process/discovery-protocol.md for state file location (.ux/ in project root). Report bugs at https://github.com/Laith0003/ux-skill/issues.

## Next prompt

After `/ux-research` (planning):
- Run the study
- `/ux-research --synthesize` — dispatch `research-synthesizer` on raw results

After `/ux-research --synthesize`:
- `/ux-design` — apply findings to a design
- `/ux-discover --frame`: re-baseline the brief on what you learned
- `/ux-workshop` — if findings open a bigger question
- `/ux-next` — let the conductor pick

---

## v2 Python integration

Research inputs (interviews, analytics, A/B results, support tickets, competitive sites) get synthesized into a Brief object that feeds the recommender.

### Synthesize research into recommender-ready Brief

After collecting and reading research artefacts, the LLM's job is to extract:
- `audience` (specific, not generic)
- `tone` (3-5 words from what users said matters)
- `must_have` (from analytics + tickets — pain points fixed = required)
- `forbidden` (from competitive sites — patterns to avoid)
- `reference_brands` (from competitive analysis — what users praised)

Write the synthesized brief:

```bash
mkdir -p .ux
cat > .ux/last-discovery.json <<JSON
{
  "answers": {
    "project_type": "<extracted>",
    "audience": "<from interviews/analytics>",
    "primary_goal": "<top job-to-be-done>",
    "tone": "<from what users praised>",
    "must_have": "<analytics pain points + tickets>",
    "forbidden": "<from competitor anti-patterns>",
    "reference_brands": "<from competitive praise>",
    "stack": "<inferred or asked>",
    "region": "<from user data>",
    "success_metric": "<from analytics baseline>"
  }
}
JSON
```

### Verify the brief produces a sensible recommendation

```bash
python3 -m engine.cli.main --no-pretty recommend --brief-file=.ux/last-discovery.json | python3 -c "
import json, sys
r = json.load(sys.stdin)
for line in r.get('rationale', []):
    print(line)
"
```

If the recommender's rationale doesn't match what research said, the brief synthesis was wrong — iterate.

### Fallback

If the engine isn't available, produce the brief as a markdown document with the 10 fields filled in and recommend `/ux-discover` next.

© Laith Aljunaidy · MIT · Laith0003/ux-skill

Similar slash commands

All slash commands for Design →

From the same set31

The whole set →
ux-mcp The ux-mcp command starts the ux-skill engine as an MCP server over stdio, exposing 25 tools for recommendations, linting, and design-system work. CX Codex +1 ★ 110repo stars ux-image-to-code ux-image-to-code redirects image extraction calls to /ux-design --extract-only --from-image. Keeps existing image-to-UI workflows working during migration to release 4.1. CX Codex +1 ★ 110repo stars ux-frame /ux-frame forwards UX framing work to /ux-discover --frame. It remains an alias in version 4.0 and is removed in 4.1. CX Codex +1 ★ 110repo stars motion-engineer motion-engineer turns a motion brief into production frontend code with Framer Motion, GSAP or CSS. Handles durations, easing curves, spring configs and reduced-motion fallbacks. CX Codex ★ 110repo stars ux-workshop ux-workshop guides a team through five design-thinking phases, ending with an MVP plan, an owner, and a checkpoint. Use it to explore a new product opportunity. CX Codex +1 ★ 110repo stars ux-system ux-system builds a starter design system for a project that has none: tokens, foundations, component contracts and a dark theme. Useful before the first component gets written. CX Codex +1 ★ 110repo stars copy-writer copy-writer drafts production UI microcopy aligned with your voice profile, handling errors, empty screens, CTAs, and toasts. Runs standalone or through /ux-copy --fix and /ux-design. CX Codex ★ 110repo stars research-synthesizer research-synthesizer turns interviews, analytics, competitor research, experiments, and support tickets into evidence-backed design recommendations. CX Codex ★ 110repo stars

Project sponsors

Companies that keep this analytics open