survey-design

What this skill does

# Survey Design

You design survey questionnaires and analyze survey results. You operate in two modes: **design** (create survey instruments) and **analyze** (interpret results).

## Modes

Infer from the user's instruction:
- **Design** (default): Produce a complete survey questionnaire with sampling plan and analysis plan
- **Analyze**: Analyze provided survey results and produce an insight report

If unclear, default to design.

## Input handling

Follow shared foundation §7 — interview mode. When input is missing or insufficient, interview to gather at minimum:

### Design mode dimensions
| Dimension | Required | Default |
|---|---|---|
| **Research objective** | Yes | — |
| **Target audience** | Yes | — |
| **Survey type** (CSAT, NPS, product feedback, etc.) | No | Inferred from objective |
| **Export format** (Qualtrics QSF, XLSForm, SurveyJS, CSV, none) | No | Asked during setup |
| **Distribution channel** (email, in-app, SMS, QR) | No | Email |
| **Sample size / confidence requirements** | No | 95% confidence, 5% margin |
| **Existing questions to include** | No | None |

### Analyze mode dimensions
| Dimension | Required | Default |
|---|---|---|
| **Survey results data** | Yes | — |
| **Original research questions** | No | Inferred from data |
| **Framework used** (NPS, CSAT, etc.) | No | Detected from data |

**Exit interview when**: Research objective and target audience are clear (design) or data is provided (analyze).

## Phase 1 — Setup

### 1. Detect mode

If the user provides survey results → analyze mode. Otherwise → design mode.

### 2. Collect input

**Design mode:** Accept research objective as text, business case reference, or description.
**Analyze mode:** Accept survey results as pasted data, file path, or CSV.

### 3. Confirm scope (design mode)

Present detected scope:

```
**Research objective**: [objective]
**Target audience**: [audience]
**Survey type**: [type]
**Distribution channel**: [channel]
**Confidence / Margin of error**: [95% / 5%]
```

### 4. Ask export format

> "Which survey tool would you like to export to?"
>
> 1. **Qualtrics** (QSF JSON format)
> 2. **XLSForm** (ODK/KoBoToolbox/SurveyCTO compatible)
> 3. **SurveyJS** (open-source JSON format)
> 4. **CSV** (simple question list, importable to most tools)
> 5. **None** (markdown only)

The survey will always be produced in human-readable markdown. The export format is an additional machine-readable output.

### 5. Ask diagram render mode and output path

Ask diagram render mode and output path per the `diagram-rendering` mixin. Default output path: `/documentation/[case]/survey-design/`

---

## Design Mode

## Phase 2 — Research Questions

Define 3-7 specific research questions that the survey must answer. Each question maps to one or more survey questions.

| # | Research question | Survey questions | Framework |
|---|---|---|---|
| RQ-1 | [what we need to learn] | Q[x], Q[y] | [NPS/CSAT/custom/etc.] |

Present to user for confirmation.

## Phase 3 — Framework Selection

Select the appropriate framework(s) based on research objective:

| Framework | When to use | Question format |
|---|---|---|
| **NPS** | Customer loyalty, likelihood to recommend | Single 0-10 scale + open follow-up |
| **CSAT** | Satisfaction with specific interaction/product | 1-5 satisfaction scale |
| **CES** | Ease of interaction/process | 1-7 effort scale |
| **SUS** | System/product usability | 10 standardized items, 1-5 scale |
| **Kano** | Feature prioritization | Functional + dysfunctional question pairs |
| **MaxDiff** | Importance ranking without scale bias | Best-worst selection from item sets |
| **Van Westendorp** | Price sensitivity | 4 price perception questions |
| **Custom** | General market research, exploratory | Mix of question types |

Multiple frameworks can be combined in one survey.

## Phase 4 — Questionnaire Construction

Build the questionnaire using **funnel structure**:

### Section order
1. **Screening / warm-up** — qualifying questions, easy to answer
2. **Core questions** — main research topics, most important questions
3. **Deep-dive** — specific, detailed, or sensitive questions
4. **Framework questions** — NPS/CSAT/CES/SUS/Kano items
5. **Open-ended** — 2-3 maximum, for qualitative depth
6. **Demographics** — always last

### Question types

| Type | Format | Use for |
|---|---|---|
| **Multiple choice** | Single or multi-select | Categorization, preferences |
| **Likert scale** | 5 or 7 point, all anchors labeled | Attitudes, agreement, satisfaction |
| **Ranking** | Drag-and-drop or numbered | Priority ordering |
| **Matrix / grid** | Multiple items on same scale | Efficient multi-attribute rating |
| **NPS** | 0-10 numeric scale | Loyalty measurement |
| **Open-ended** | Free text | Qualitative insight, follow-up |
| **MaxDiff** | Best-worst from sets | Importance without scale bias |
| **Van Westendorp** | 4 price questions | Price sensitivity |
| **Kano** | Functional + dysfunctional pairs | Feature classification |

### Skip logic

Define conditional paths:

```
If Q3 = "No" → Skip to Q7
If Q5 ≤ 6 (Detractor) → Show Q5a (open: "What could we improve?")
If Q5 ≥ 9 (Promoter) → Show Q5b (open: "What do you value most?")
```

### Question format per item

```markdown
**Q[N]**: [Question text]
- Type: [multiple choice / Likert 5pt / etc.]
- Required: [yes/no]
- Options: [list of response options with codes]
- Skip logic: [condition → action]
- Research question: [RQ-N]
- Randomize: [yes/no]
```

### Constraints
- 10-25 questions total
- Estimated completion time: 5-10 minutes
- Maximum 2-3 open-ended questions
- All Likert scales: label every anchor point
- Balance positive/negative wording to prevent acquiescence bias

## Phase 5 — Bias Review

Check every question against 6 bias types:

| # | Question | Leading? | Double-barreled? | Order bias? | Social desirability? | Acquiescence? | Loaded language? | Status |
|---|---|---|---|---|---|---|---|---|
| Q1 | [text] | ✅ Pass | ✅ Pass | ✅ Pass | ✅ Pass | ✅ Pass | ✅ Pass | Clean |
| Q2 | [text] | ⚠️ Flag | ✅ Pass | ✅ Pass | ✅ Pass | ✅ Pass | ✅ Pass | Revised |

If bias is detected, revise the question and show both original and revised versions.

## Phase 6 — Sampling Plan

| Element | Value |
|---|---|
| **Population** | [who] |
| **Sampling method** | [random / stratified / convenience / snowball] |
| **Confidence level** | [95%] |
| **Margin of error** | [5%] |
| **Expected response rate** | [X%] |
| **Required responses** | n = Z² × p × (1-p) / E² = [calculated] |
| **Invitations to send** | Required responses / expected response rate = [calculated] |
| **Distribution channel** | [email / in-app / SMS / QR] |
| **Timeline** | [collection period] |
| **Reminder strategy** | [first reminder at 48-72h, max 2-3 reminders] |

## Phase 7 — Analysis Plan

Pre-define analysis methods per question:

| Question | Type | Analysis method | Cross-tabs |
|---|---|---|---|
| Q1 | Multiple choice | Frequency distribution, chi-square | By segment, by age |
| Q2 | Likert 5pt | Mean, SD, t-test vs neutral | By segment |
| Q3 | NPS | NPS calculation, promoter/detractor distribution | By cohort |
| Q4 | Open-ended | Thematic coding, sentiment analysis | — |

## Phase 8 — Pre-test Protocol

### Cognitive interview guide
- Test with 5-10 representative respondents
- Think-aloud protocol: ask respondents to verbalize their thought process
- Probe: "What did you think this question was asking?" and "How did you arrive at your answer?"
- Document misunderstandings, confusion, or unexpected interpretations

### Pilot test plan
- Deploy to 30-50 respondents before full launch
- Check: completion rate, drop-off points, average time, skip logic paths, open-ended response quality
- Revise if completion rate <70% or average time >12 minutes

## Phase 9 — Export Format

### Always produced: Markdown questionnaire
Human-readable survey document with all questions, options, logic, and metadata.

### Optional: Machine-readable expo