ux-research-synthesize

ux-research-synthesize

Synthesize UX research findings into themed insights, executive summaries, and prioritized recommendations.

Context Files

• $JAAN_LEARN_DIR/jaan-to-ux-research-synthesize.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_TEMPLATES_DIR/jaan-to-ux-research-synthesize.template.md - Synthesis report template
• $JAAN_CONTEXT_DIR/config.md - Project configuration (if applicable)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-templates.md - Theme cards, recommendation format, executive brief template, quality checklist

Input

Study Name & Data Sources: $ARGUMENTS

• If file paths provided → Read transcripts directly
• If directory provided → Scan for all research files
• If empty → Interactive wizard (ask for study name and data sources)

Accepted data sources:

• Transcripts (interview notes, session recordings)
• Survey responses
• Observation notes
• Existing research files
• URLs to research repositories

---

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: ux-research-synthesize Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_ux-research-synthesize

---

PHASE 1: Analysis (Read-Only)

Step 1: Input Collection & Validation

Parse $ARGUMENTS to identify:

1. Study name - First argument or ask if not provided
2. Data sources - Remaining arguments (file paths, directories, URLs)

For each data source:

• If file path: Use Read to validate file exists and is readable
• If directory: Use Glob to find all .txt, .md, .docx, .pdf files
• If URL: Note for later retrieval
• If empty: Ask: "Please provide file paths, directory path, or paste transcript text"

Build and display data summary.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Data Source Summary Format" for the display format.

If any file is missing or unparseable, report error and ask for correction.

Step 2: Synthesis Mode Selection

Present three synthesis modes: [1] Speed, [2] Standard (recommended), [3] Cross-Study.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Synthesis Mode Descriptions" for full mode details to present to the user.

Ask: "Choose mode: [1/2/3]"

Store selection as {synthesis_mode}.

Show expected deliverables:

"Mode: {synthesis_mode} Time estimate: {time_estimate} Output: {deliverables_description}"

Step 3: Research Questions Clarification

Ask: "What are your research questions? (1-3 max)"

If unclear, provide common templates from reference material.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Research Question Templates" for the template list.

Confirm 1-3 research questions maximum.

Critical: Every theme must tie back to these questions.

Step 4: Data Familiarization (AI-Assisted)

For Speed mode: Read first 200 lines of each transcript For Standard/Cross-Study: Read complete transcripts

Use Task tool to launch AI familiarization agent:

Prompt:

Read all provided transcripts. Identify:
1. Recurring topics mentioned by multiple participants
2. Strong emotional reactions (frustration, delight, confusion)
3. Contradictory statements between participants
4. Participant language patterns and terminology

Do NOT generate themes yet — only familiarize with the data landscape.

Return:
- Summary of data landscape (5-7 sentences)
- Participant count identified
- Session types observed
- Data quality notes (any transcription issues, missing context)

Human reviews AI summary:

• Check for accuracy
• Note any missed patterns
• Confirm participant count matches expectations

Step 5: Initial Coding (AI-Assisted with Human Validation)

Use Task tool for AI coding agent:

Prompt:

Generate descriptive codes for meaningful data segments from the transcripts.
Use both semantic (surface) and latent (underlying) codes.

For each code provide:
- Label (2-4 words)
- Brief definition
- Supporting quote with participant ID
- Line reference

Return codebook with 30-40 codes maximum.
Format: Table with Code | Definition | Supporting Quote | Participant ID | Line Reference

Human validates codebook:

Display AI-generated codebook in conversation.

Check for:

• Vague codes without clear definition
• Overlapping codes that should be merged
• Codes without examples/quotes
• Every code has at least 2 participant quotes

Ask: "Codebook Review

{display codebook}

Approve this codebook or refine? [Approve/Refine/Restart]"

If Refine: Ask "What should be changed?" and regenerate If Restart: Start Step 5 over with different approach If Approve: Continue to Step 6

Step 6: Theme Development (Human-Led with AI Support)

Ask: "Should themes be generated: [1] Inductively - From data patterns (let themes emerge organically) [2] Deductively - From framework (e.g., UX mental models, needs, pain points, workarounds) [3] Hybrid - Start with framework + add emergent codes ← Recommended"

Use Task tool for AI theme clustering:

Prompt:

Group the approved codes into 4-6 candidate themes.

For each theme provide:
1. Descriptive name
2. Codes belonging to theme (list all relevant codes)
3. 2-3 sentence narrative explaining the pattern
4. Tensions or contradictions within theme (if any)

Be explicit about reasoning for each grouping.

Human reviews themes:

Display candidate themes in conversation.

Check for:

• Coherence: Do codes fit together logically?
• Distinctness: Are themes overlapping or duplicative?
• Coverage: Do themes answer research questions?
• Count: 3-8 themes total (optimal)

Rename themes from descriptive to interpretive:

• ❌ Bad: "Navigation Issues" (topic label)
• ✅ Good: "Users Navigate by Trial and Error, Not Design Cues" (interpretive insight)

Ask: "Theme Review

{display themes with codes}

Theme count: {N} {optimal: 3-8 | ⚠️ flag if outside range}

Approve themes or refine? [Approve/Split/Merge/Rename]"

Options:

• Approve: Continue to Step 7
• Split: "Which theme to split?" → Human selects → Ask for split criteria
• Merge: "Which themes to merge?" → Human selects → Create combined theme
• Rename: "Which theme to rename?" → Human provides new interpretive name

Step 7: Evidence Linking & Participant Coverage Check

For each approved theme, compile supporting evidence:

1. Extract quotes - Minimum 2-3 quotes from different participants

2. Include context:

   • Task participant was performing
   • Timing in session (early/mid/late)
   • Non-verbal cues (hesitation, frustration, emphasis)
   • Preceding/following discussion summary

3. Build traceability matrix: Theme → Codes → Quotes → Participant IDs

4. Track participant contribution:

   • Count quotes per participant per theme
   • Flag if any participant contributes >25% of quotes for a theme

Display participant coverage matrix per theme and flag imbalanced coverage (>25% from single participant).

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md sections "Participant Coverage Matrix Format" and "Imbalanced Coverage Handling" for display format and remediation options.

Step 8: Prioritization & Recommendation Planning

For each theme, apply the Nielsen severity framework (0-4 scale). Ask the user to rate severity for each theme.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Nielsen Severity Framework (0-4 Scale)" for the full rating scale descriptions.

Calculate priority score using Severity x Frequency.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Priority Score Calculation" for the formula.

Apply Impact x Effort matrix. Ask the user to estimate effort for each theme, then classify into quadrants.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Impact x Effort Matrix" for effort estimation scale and quadrant definitions.

Generate draft recommendations using the action-outcome-evidence template.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Draft Recommendation Template" for the format and example.

---

HARD STOP - Human Review Gate

Present analysis summary for approval:

SYNTHESIS ANALYSIS SUMMARY
════════════════════════════════════════
Mode: {Speed | Standard | Cross-Study}
Study: {study_name}
Research Questions:
  1. {question_1}
  2. {question_2}
  3. {question_3}

Data Sources: {N} files
  Participants: {n} total
  Transcripts analyzed: {n}

THEMES IDENTIFIED: {N} themes {optimal: 3-8 | ⚠️ flag if outside}

  Priority 1 (High Severity × High Frequency):
    - {theme_name} — Severity {0-4}, {frequency}%, {n} participants
      Quick Win / Big Bet / Fill-In / Money Pit: {quadrant}

  Priority 2:
    - {theme_name} — Severity {0-4}, {frequency}%, {n} participants
      {quadrant}

  Priority 3:
    - {theme_name} — Severity {0-4}, {frequency}%, {n} participants
      {quadrant}

QUALITY CHECKS:
  ✓ Theme count: {N} (optimal: 3-8)
  ✓ Participant coverage: {Balanced | ⚠️ Imbalanced}
  ✓ Evidence traceability: {Complete | ⚠️ Gaps in Theme X}
  ✓ Research questions addressed: {N}/{total}
  {⚠️ Any warnings or issues}

REPORT SECTIONS TO GENERATE:
  ✓ Executive Summary (1 page max)
  ✓ {N} Themed Findings with evidence
  ✓ Prioritized Recommendations ({N} total)
  ✓ Methodology Note with limitations
  {✓ Appendix (if Standard+ mode)}

════════════════════════════════════════

"Proceed with synthesis report generation? [y/edit/n]"

Do NOT proceed to Phase 2 without explicit approval.

If edit: Ask "What should be changed?" and return to appropriate step If n: Stop and ask for next steps

---

PHASE 2: Generation (Write Phase)

Step 9: Generate ID and Output Paths

Source ID generator utility:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"

Generate sequential ID and output paths:

# Define subdomain directory
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/ux/research"
mkdir -p "$SUBDOMAIN_DIR"

# Generate next ID
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")

# Generate slug from study name
slug=$(echo "{study_name}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)

# Create folder and file paths
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"
MAIN_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-synthesis-${slug}.md"
EXEC_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-exec-brief-${slug}.md"

Preview output configuration:

"Output Configuration

• ID: {NEXT_ID}
• Folder: $JAAN_OUTPUTS_DIR/ux/research/{NEXT_ID}-{slug}/
• Main file: {NEXT_ID}-synthesis-{slug}.md
• Exec brief: {NEXT_ID}-exec-brief-{slug}.md"

Step 10: Generate Main Synthesis Report

Use template from: $JAAN_TEMPLATES_DIR/jaan-to-ux-research-synthesize.template.md

Fill all template sections:

Header

• Study name: {study_name}
• Date: {current_date YYYY-MM-DD}
• Participants: {n} total
• Method: {research_method from data familiarization}
• Mode: {synthesis_mode}
• Research Questions: {list 1-3 questions}

Executive Summary (1 page max)

Structure:

1. Open with powerful user quote - Select most emotionally resonant quote
2. Highlights (what's working well) - 2-3 bullets of positive findings
3. Lowlights (top 3-5 issues) - Prioritized by severity × frequency
4. How to turn lowlights into highlights - Clear next steps (actionable bullets)

Key Findings

For each theme (ordered by Priority Score descending):

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-templates.md section "Theme Card Structure" for the full theme card template and priority badge definitions.

Recommendations

For each theme with actionable recommendation:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-templates.md section "Recommendation Format (Problem-Solution)" for the full INSIGHT/SO WHAT/NOW WHAT template.

Methodology Note & Appendix

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md sections "Methodology Note Structure" and "Appendix Sections" for detailed content requirements.

Step 11: Generate Executive Brief

Auto-generate 1-page standalone summary from main report.

Extract from main report:

1. Opening quote: Use same powerful quote from Executive Summary
2. Highlights: Copy from Executive Summary (2-3 bullets)
3. Lowlights: Copy top 3-5 issues from Executive Summary
4. Next steps: Copy action items from Executive Summary
5. Visual (if applicable): Add simple table showing priority breakdown

Constraints: Max 1 page (~300-400 words), no methodology/raw data/jargon, standalone.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-templates.md section "Executive Brief Format" for the full markdown template.

Step 12: Quality Check (Pre-Write Validation)

Apply the full quality checklist before preview. If any check fails, revise report before preview.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-templates.md section "Quality Checklist (Pre-Write Validation)" for the complete checklist covering Executive Summary, Themes, Recommendations, Evidence & Traceability, Methodology, and Cross-Study checks.

Step 13: Preview & Approval

Show both reports in conversation:

1. Main Synthesis Report (full markdown)
2. Executive Brief (1-page summary)

"Preview: Synthesis Outputs

{display full main report}

---

{display executive brief}

---

Write these outputs? [y/n]"

If n: Ask "What should be changed?" and return to Step 10/11

Step 14: Write Outputs

If approved, write files:

1. Create output folder:

mkdir -p "$OUTPUT_FOLDER"

2. Write main synthesis report:

cat > "$MAIN_FILE" <<'EOF'
{generated synthesis report with Executive Summary, Key Findings, Recommendations, Methodology, Appendix}
EOF

3. Write executive brief:

cat > "$EXEC_FILE" <<'EOF'
{generated 1-page executive brief}
EOF

4. Update subdomain index:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"

# Extract 1-2 sentence summary from Executive Summary section
EXEC_SUMMARY="{extract first 1-2 sentences from Executive Summary of main report}"

add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{Study Name}" \
  "$EXEC_SUMMARY"

5. Confirm completion:

"✓ Synthesis report written to: $JAAN_OUTPUTS_DIR/ux/research/{NEXT_ID}-{slug}/{NEXT_ID}-synthesis-{slug}.md ✓ Executive brief written to: $JAAN_OUTPUTS_DIR/ux/research/{NEXT_ID}-{slug}/{NEXT_ID}-exec-brief-{slug}.md ✓ Index updated: $JAAN_OUTPUTS_DIR/ux/research/README.md"

Step 15: Capture Feedback

"Any feedback or improvements needed? [y/n]"

If yes:

1. Ask: "What should be improved?"
2. Offer options:

   "How should I handle this? [1] Fix now - Update this synthesis [2] Learn - Save for future syntheses [3] Both - Fix now AND save lesson"

Options:

• [1] Fix now: Revise reports, re-preview, re-write to same paths
• [2] Learn: Run /jaan-to:learn-add ux-research-synthesize "{feedback}"
• [3] Both: Do both

---

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Template-driven output structure
• Generic across platforms and design systems
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/ux-research-synthesize-reference.md section "Definition of Done Checklist" for the full 15-point checklist.