---
name: survey-builder
description: "Creates customer feedback surveys with strategically ordered questions, response scales, and analysis frameworks for measuring satisfaction, gathering product feedback, or validating new ideas. Use when a user needs to collect customer feedback, wants to run a Net Promoter Score survey, or needs to validate a product idea before building it."
allowed-tools: Read Write Glob mcp__claude_ai_Notion__notion-create-database mcp__claude_ai_Notion__notion-create-pages mcp__claude_ai_Notion__notion-search
metadata:
  author: matthewhitcham
  version: "1.0"
---

# Survey Builder

## When to Use This Skill

Use this skill when you need to:
- Create a customer satisfaction (CSAT) or Net Promoter Score (NPS) survey
- Build a product feedback survey to improve an existing offering
- Design a market validation survey before building a new product or feature
- Write a post-purchase survey for an e-commerce store or digital product
- Construct a churn exit survey to understand why customers are leaving
- Collect structured feedback from clients, students, members, or event attendees

**DO NOT** use this skill for:
- Academic or scientific research surveys (different methodology and IRB requirements)
- Medical or psychological assessments (regulated instruments)
- Employee engagement or HR surveys (different legal and privacy considerations)
- Quizzes, tests, or assessments with right/wrong answers
- Polls with a single question (just write the question directly)

---

## Quick Reference: Survey Capabilities

| Feature | Details |
|---------|---------|
| Survey types | 6 templates (CSAT, NPS, Product Feedback, Market Validation, Post-Purchase, Churn Exit) |
| Question types | 6 formats (Multiple Choice, Rating Scale, Open-Ended, Yes/No, Matrix/Grid, Ranking) |
| Response scales | 3 validated scales (Likert 5-point, NPS 0-10, Satisfaction emoji) |
| Question budget | 8-12 default, max 15 with justification |
| Analysis frameworks | NPS calculation, CSAT scoring, thematic analysis, response rate benchmarks |
| Output formats | Markdown document, optional Notion question bank database |

## Quick Reference: Survey Types

| Type | Questions | Ideal Length | Best Timing | Anchor Question |
|------|-----------|-------------|-------------|-----------------|
| **Customer Satisfaction (CSAT)** | 6-10 | 3-5 minutes | 24-48 hours after interaction | "How satisfied are you with your experience?" (1-5) |
| **Net Promoter Score (NPS)** | 5-8 | 2-3 minutes | 14-30 days after purchase or onboarding | "How likely are you to recommend us?" (0-10) |
| **Product Feedback** | 8-12 | 5-7 minutes | After 2+ weeks of active usage | "How well does this product meet your needs?" (1-5) |
| **Market Validation** | 8-10 | 4-6 minutes | Before building; target ideal customer profile | "How would you solve this problem today?" (open-ended) |
| **Post-Purchase** | 6-8 | 3-4 minutes | 3-7 days after delivery or completion | "How satisfied are you with your purchase?" (1-5) |
| **Churn Exit** | 5-7 | 2-3 minutes | Within 24 hours of cancellation | "What is the primary reason you are leaving?" (multiple choice) |

## Quick Reference: Question Types

| Type | Format | When to Use | Example |
|------|--------|-------------|---------|
| **Multiple Choice** | Select one from a list | Categorize responses, force clear answers | "How did you hear about us?" with 5 options |
| **Rating Scale (1-5)** | Numbered scale with labels | Measure intensity of sentiment | "How easy was the checkout process?" 1=Very Difficult, 5=Very Easy |
| **Rating Scale (0-10)** | Numbered scale, NPS format | Net Promoter Score questions only | "How likely are you to recommend us to a friend?" 0=Not at all, 10=Extremely likely |
| **Open-Ended** | Free text response | Capture nuance, stories, suggestions | "What is one thing we could improve?" |
| **Yes/No** | Binary choice | Screen or filter, confirm simple facts | "Did your order arrive on time?" |
| **Matrix/Grid** | Rate multiple items on same scale | Compare features or attributes efficiently | Rate satisfaction with: support, speed, quality (each 1-5) |
| **Ranking** | Drag to order or number preferences | Prioritize features or preferences | "Rank these features by importance: A, B, C, D" |

## Quick Reference: Response Scales

**Likert 5-Point (satisfaction, agreement, ease):**

| Score | Satisfaction Label | Agreement Label | Ease Label |
|-------|--------------------|-----------------|------------|
| 1 | Very Dissatisfied | Strongly Disagree | Very Difficult |
| 2 | Dissatisfied | Disagree | Difficult |
| 3 | Neutral | Neither Agree nor Disagree | Neutral |
| 4 | Satisfied | Agree | Easy |
| 5 | Very Satisfied | Strongly Agree | Very Easy |

**NPS 0-10:**

| Range | Category | Meaning |
|-------|----------|---------|
| 0-6 | Detractors | Unhappy, may churn or leave negative reviews |
| 7-8 | Passives | Satisfied but unenthusiastic, vulnerable to competitors |
| 9-10 | Promoters | Loyal, will refer others and drive growth |

**Formula:** NPS = % Promoters - % Detractors (range: -100 to +100)

**Satisfaction Emoji Scale (lightweight, mobile-friendly):** 1=Very Unhappy (angry face), 2=Unhappy (sad face), 3=Okay (neutral face), 4=Happy (smiling face), 5=Love It (heart-eyes face). Use only if the user specifically requests a lightweight mobile-first survey.

**DEFAULT: Likert 5-point for CSAT, NPS 0-10 for NPS, emoji scale only on explicit request.**

---

## Core Workflow

EVERY SURVEY STARTS WITH A CLEAR GOAL BEFORE A SINGLE QUESTION IS WRITTEN -- A SURVEY WITHOUT A DEFINED PURPOSE PRODUCES DATA NOBODY CAN ACT ON.

### Step 1: Strategy

Gather these details before writing any questions:

1. **Survey goal** -- what decision will this data inform? (required)
2. **Survey type** -- CSAT, NPS, Product Feedback, Market Validation, Post-Purchase, or Churn Exit (default: infer from goal)
3. **Target respondent** -- who is taking this survey? (required)
4. **Distribution method** -- email, in-app popup, link on website, social media, QR code (default: email)
5. **Question count budget** -- how many questions max? (default: 8-12)
6. **Incentive** -- discount code, entry into a drawing, free resource, none (default: none)
7. **Existing data** -- does the user already have feedback, reviews, or support tickets to reference?

If the user provides items 1 and 3, proceed with defaults for the rest.

**Brief template for vague requests:**

```
I'll build your survey. Quick details needed:

1. What decision will this survey inform? (e.g., improve onboarding, validate a new feature)
2. Who is taking the survey? (e.g., paying customers, free trial users, newsletter subscribers)
3. How will you send it? (email, in-app, link, social media -- default: email)
4. Max number of questions? (default: 10)
5. Any incentive for completing it? (discount, raffle, free resource -- default: none)
```

**GATE: Do not proceed until you have: survey goal AND target respondent.**

### Step 2: Build

Write questions following survey science principles in this exact order:

1. **Start with a screening or warmup question** -- easy, non-threatening, builds momentum
2. **Group questions by topic** -- do not jump between themes
3. **Place the anchor question early** -- CSAT or NPS core question in position 2-4
4. **Put sensitive or hard questions in the middle** -- pricing, complaints, competitor usage
5. **End with an open-ended question** -- "Is there anything else you would like to share?"
6. **Demographics last** -- only if needed, and explain why you are asking

**Question writing rules -- apply to EVERY question:**

- One concept per question. Never double-barreled ("How satisfied are you with our product and support?")
- Neutral wording. Never leading ("How much did you love our new feature?")
- Balanced response scales. Include negative, neutral, and positive options
- Include "N/A" or "Prefer not to say" where the question may not apply to all respondents
- Keep questions under 25 words
- Avoid jargon, abbreviations, and internal terminology
- Use "you" and "your" -- direct and personal
- Default to required questions. Mark optional questions explicitly.

**For each question, specify:**

```
Q[#]: [Question text]
Type: [Multiple Choice / Rating Scale 1-5 / Rating Scale 0-10 / Open-Ended / Yes/No / Matrix / Ranking]
Options: [List response options if applicable]
Required: [Yes / No]
Logic: [Skip logic or branching if applicable, otherwise "None"]
```

### Step 3: Present

Show the complete survey for approval with:
- Survey title and introduction text (what the survey is about, estimated completion time, incentive if any)
- All questions numbered with types, options, and logic
- Thank-you/completion message
- Total estimated completion time

**GATE: Do not write files or create Notion databases until the user approves the survey.**

### Step 4: Deliver

After approval, deliver in one or both formats:

**Format A: Markdown document (always)**

Save to `survey/` (or user-specified path):

```
survey/
├── survey.md                # Complete survey with all questions
└── analysis-framework.md    # How to interpret results
```

**Format B: Notion question bank (if user requests)**

1. Call `notion-search` to find the target page
2. Call `notion-create-database` with 8 properties: Question Text (title), Question Number (number), Question Type (select: Multiple Choice, Rating Scale 1-5, Rating Scale 0-10, Open-Ended, Yes/No, Matrix, Ranking), Response Options (rich_text), Required (checkbox), Logic Notes (rich_text), Survey Section (select: Warmup, Core, Sensitive, Closing, Demographics), Status (select: Draft, Approved, In Use, Retired)
3. Call `notion-create-pages` to add all questions as rows
4. Confirm creation with the user

**Always include the analysis framework with delivery:**

- How to calculate the primary metric (NPS score, CSAT percentage, etc.)
- Response rate benchmarks by channel
- How to analyze open-ended responses (thematic coding)
- When to act vs. when to collect more data

---

## Analysis Framework

### NPS Calculation

```
Total responses: [N]
Promoters (9-10):  [count] = [%]
Passives (7-8):    [count] = [%]
Detractors (0-6):  [count] = [%]

NPS = % Promoters - % Detractors

Interpretation:
  -100 to 0:   Needs urgent attention
  1 to 30:     Good, room to improve
  31 to 50:    Strong
  51 to 70:    Excellent
  71 to 100:   World-class
```

### CSAT Calculation

```
CSAT Score = (Number of satisfied responses / Total responses) x 100

"Satisfied" = respondents who selected 4 or 5 on a 1-5 scale

Interpretation:
  Below 60%:   Poor — investigate immediately
  60-70%:      Below average — prioritize improvements
  70-80%:      Average — identify quick wins
  80-90%:      Good — maintain and optimize
  Above 90%:   Excellent — protect what is working
```

### Response Rate Benchmarks

| Channel | Average Rate | Good Rate | Actions to Improve |
|---------|-------------|-----------|-------------------|
| Email (existing customers) | 10-15% | 20-30% | Personalize subject line, send from a person not a brand |
| In-app popup | 15-25% | 30-40% | Trigger after positive action, keep under 5 questions |
| Post-purchase email | 5-10% | 15-20% | Send within 3-7 days, offer incentive |
| Link on website | 1-3% | 5-10% | Prominent placement, clear value proposition |
| Social media | 1-5% | 5-10% | Use stories/polls for single questions, link for full surveys |

### Open-Ended Response Analysis

1. Read all responses once without categorizing
2. Identify recurring themes (aim for 5-8 categories)
3. Code each response to one or more themes
4. Count frequency per theme
5. Pull 2-3 representative quotes per theme
6. Rank themes by frequency and business impact
7. Present as: Theme name, frequency count, sample quotes, recommended action

---

## Example 1: Post-Purchase CSAT Survey for an Online Course

**User request:** "I sell a $297 online course on freelance copywriting. 50 students per cohort. I want to measure satisfaction and figure out what to improve for the next cohort."

**Step 1 (Strategy):** Goal: improve course content for next cohort. Type: Post-Purchase. Target: students who completed the course. Distribution: email. Budget: 10 questions. Incentive: early access to bonus module.

**Step 2 (Build):**

```
SURVEY: Freelance Copywriting Masterclass — Student Feedback
Estimated time: 4-5 minutes
Incentive: Complete this survey for early access to the bonus portfolio-building module.

Q1: Which best describes your experience level when you started the course?
Type: Multiple Choice
Options: Complete beginner / Some experience (under 1 year) / Intermediate (1-3 years) / Advanced (3+ years)
Required: Yes
Logic: None

Q2: Overall, how satisfied are you with the Freelance Copywriting Masterclass?
Type: Rating Scale 1-5
Options: 1=Very Dissatisfied, 2=Dissatisfied, 3=Neutral, 4=Satisfied, 5=Very Satisfied
Required: Yes
Logic: None

Q3: How likely are you to recommend this course to a friend or colleague?
Type: Rating Scale 0-10
Options: 0=Not at all likely, 10=Extremely likely
Required: Yes
Logic: None

Q4: Rate your satisfaction with each of the following:
Type: Matrix/Grid (1-5 scale: Very Dissatisfied to Very Satisfied)
Items:
  - Course content and curriculum
  - Video lesson quality
  - Assignments and exercises
  - Community and peer interaction
  - Instructor responsiveness
Required: Yes
Logic: None

Q5: Which module was most valuable to you?
Type: Multiple Choice
Options: Module 1: Copywriting Fundamentals / Module 2: Finding Clients / Module 3: Writing Sales Pages / Module 4: Email Sequences / Module 5: Pricing and Proposals / Module 6: Building a Portfolio
Required: Yes
Logic: None

Q6: Which module needs the most improvement?
Type: Multiple Choice
Options: Module 1: Copywriting Fundamentals / Module 2: Finding Clients / Module 3: Writing Sales Pages / Module 4: Email Sequences / Module 5: Pricing and Proposals / Module 6: Building a Portfolio / None — all modules were strong
Required: Yes
Logic: None

Q7: Have you landed a freelance copywriting client since completing the course?
Type: Multiple Choice
Options: Yes, one client / Yes, multiple clients / Not yet, but actively pitching / Not yet, still building my portfolio / I was already freelancing before the course
Required: Yes
Logic: If "Not yet, but actively pitching" or "Not yet, still building my portfolio" -> show Q8

Q8: What is the biggest obstacle preventing you from landing your first client?
Type: Open-Ended
Required: No
Logic: Only shown if Q7 = "Not yet" options

Q9: What is one specific change that would make this course significantly better?
Type: Open-Ended
Required: Yes
Logic: None

Q10: Is there anything else you would like to share about your experience?
Type: Open-Ended
Required: No
Logic: None

THANK YOU MESSAGE:
Thank you for your feedback! Your responses will directly shape the next cohort's experience. Check your email within 48 hours for early access to the bonus portfolio-building module.
```

**Step 4 (Delivery):** Two files saved to `survey/`. Analysis framework included with CSAT calculation (target: 80%+), NPS calculation, module comparison matrix, and thematic coding guide for Q8, Q9, Q10.

---

## Example 2: Market Validation Survey for a New SaaS Idea

**User request:** "I want to build a client portal tool for freelancers. Before I start coding, I need to know if freelancers would actually pay for this. I have a newsletter with 2,000 subscribers who are freelancers."

**Step 1 (Strategy):** Goal: validate demand and willingness to pay before building. Type: Market Validation. Target: freelancers on email list. Distribution: email. Budget: 8 questions. Incentive: none (keep it pure).

**Step 2 (Build):**

```
SURVEY: Client Management for Freelancers — Quick Research
Estimated time: 3-4 minutes

Q1: What type of freelance work do you primarily do?
Type: Multiple Choice
Options: Design and creative / Writing and content / Development and tech / Consulting and strategy / Marketing and ads / Other (please specify)
Required: Yes
Logic: None

Q2: How do you currently share deliverables and updates with clients?
Type: Multiple Choice (select all that apply)
Options: Email attachments / Google Drive or Dropbox links / Project management tool (Asana, Trello, etc.) / Custom-built portal or website / I have no consistent system
Required: Yes
Logic: None

Q3: How satisfied are you with your current method of sharing work with clients?
Type: Rating Scale 1-5
Options: 1=Very Dissatisfied, 2=Dissatisfied, 3=Neutral, 4=Satisfied, 5=Very Satisfied
Required: Yes
Logic: None

Q4: How often do clients ask you for a status update that you have already provided?
Type: Multiple Choice
Options: Never / Rarely (once a month or less) / Sometimes (a few times a month) / Often (weekly) / Constantly (multiple times a week)
Required: Yes
Logic: None

Q5: If a tool existed that gave each client a branded portal with project status, shared files, invoices, and a message thread in one place, how interested would you be?
Type: Rating Scale 1-5
Options: 1=Not at all interested, 2=Slightly interested, 3=Moderately interested, 4=Very interested, 5=Extremely interested
Required: Yes
Logic: If 1 or 2 -> skip to Q8

Q6: What is the maximum you would pay per month for a client portal tool?
Type: Multiple Choice
Options: $0 (would only use if free) / $9-19/month / $20-39/month / $40-59/month / $60+/month
Required: Yes
Logic: Only shown if Q5 = 3, 4, or 5

Q7: Which feature would matter most to you in a client portal?
Type: Ranking
Items: Branded portal with my logo / File sharing and version history / Invoice and payment tracking / Project status timeline / Client messaging thread
Required: Yes
Logic: Only shown if Q5 = 3, 4, or 5

Q8: Is there anything else you would like to share about how you manage client work?
Type: Open-Ended
Required: No
Logic: None

THANK YOU MESSAGE:
Thank you for sharing your experience! Your input is shaping a tool built specifically for freelancers like you. I will share updates as the project develops.
```

**Step 4 (Delivery):** Two files saved to `survey/`. Analysis framework includes: interest score distribution (Q5), willingness-to-pay histogram (Q6), feature priority ranking (Q7), validation thresholds (proceed if 40%+ rate Q5 as 4 or 5 AND median WTP is $20+/month).

---

## Anti-Patterns

- **DO NOT** write leading questions. "How much did you love our product?" assumes a positive response. Write: "How satisfied are you with our product?"
- **DO NOT** create surveys longer than 15 questions without explicit justification from the user. Every question beyond 12 drops completion rates by approximately 5-10%.
- **DO NOT** use double-barreled questions. "How satisfied are you with our product and customer support?" measures two things. Split into two questions.
- **DO NOT** put demographic questions first. Demographics feel invasive as openers and increase abandonment. Place them last, and only include demographics that are necessary for analysis.
- **DO NOT** use unbalanced scales. A scale with "Terrible, Bad, Okay, Good, Great, Amazing, Outstanding" is biased toward positive responses. Use balanced options: equal negative and positive with a neutral midpoint.
- **DO NOT** make every question required. Open-ended and sensitive questions should be optional. Mandatory open-ended questions produce garbage responses like "N/A" and "nothing."
- **DO NOT** use jargon or internal language. "How would you rate our NPS touchpoint optimization?" means nothing to a customer. Write in the language your respondents actually use.
- **DO NOT** include "Other (please specify)" on every multiple choice question. Only add it when the list genuinely cannot cover all possibilities. Overuse signals lazy question design.
- **DO NOT** skip the analysis framework. A survey without a plan for interpreting results produces a spreadsheet of data nobody reads.

---

## Recovery and Troubleshooting

### User Cannot Articulate the Survey Goal

1. Ask: "What decision will you make differently based on the survey results?"
2. If still vague, offer the three most common goals for their business type:
   - "Are you trying to (a) measure satisfaction, (b) improve a specific product, or (c) validate a new idea?"
3. Pick the one they confirm and proceed
4. **If 3 clarification rounds produce no clear goal:** "A survey without a clear goal produces data you cannot act on. Let us pause and define what you want to learn before writing questions."

### User Wants More Than 15 Questions

1. Explain the tradeoff: "Each question beyond 12 drops your completion rate by 5-10%. A 20-question survey may get half the responses of a 10-question survey."
2. Offer to split into two shorter surveys sent at different times
3. Prioritize: "Which 5 questions are most critical to your decision? Let us start there and add only what is essential."
4. **Maximum hard cap: 20 questions.** Beyond this, refuse and explain why.

### User Wants to Survey People They Have No Access To

1. Clarify distribution: "How will you reach these respondents? Do you have their email, or are they in a community you can post to?"
2. If no access: suggest building the audience first (email list, social following, community membership)
3. Offer to create the survey now and hold it until distribution is solved
4. **DO NOT promise response rates for audiences the user cannot reach.**

### Notion Page Not Found

1. Ask the user for the exact page title
2. Try `notion-search` with a shorter keyword
3. Confirm the Notion integration has access to that page
4. **After 3 failed searches:** "I cannot locate that page. Please verify the page exists in Notion and that the integration has access. Check Settings > Connections."

### User Wants to Edit an Approved Survey

1. Read the existing survey file with `Read`
2. Make requested changes
3. Re-verify question order follows survey science principles (warmup first, anchor early, sensitive in middle, open-ended and demographics last)
4. Re-present the updated survey for approval
5. Overwrite the file on second approval

### Low Response Rate After Launch

Advise the user: shorten to 5-7 questions, personalize the invitation with their first name, send from a person not a brand, send Tuesday-Thursday 10am-2pm in the recipient's timezone, add an incentive if none exists, follow up once after 5-7 days with non-responders, and test the survey themselves to verify it takes under 5 minutes.

---

## Pre-Delivery Checklist

Run this checklist before delivering any survey. **DO NOT SKIP ANY ITEM.**

| Check | What to Verify |
|-------|----------------|
| Goal defined | Survey has a clear, stated purpose tied to a decision |
| Question count | Within budget (default 8-12, max 15 unless justified) |
| Question order | Warmup first, anchor early, sensitive middle, open-ended and demographics last |
| No double-barreled | Every question measures exactly one concept |
| No leading language | All questions are neutrally worded |
| Balanced scales | Equal positive and negative options with neutral midpoint |
| N/A option | Included where a question may not apply to all respondents |
| Open-ended optional | Free-text questions are not marked as required (except the main feedback question) |
| Logic correct | Skip logic and branching conditions are accurate |
| Introduction text | Survey has a title, purpose statement, time estimate, and incentive (if any) |
| Thank-you message | Survey ends with a completion message |
| Analysis framework | Delivery includes how to calculate metrics and interpret results |
| File saved | Write tool confirmed successful save |
| Notion database | Created and populated if user requested (verify with search) |

```
Pre-Delivery Checklist:
  [x] Survey goal clearly defined
  [x] Question count within budget
  [x] Question order follows survey science
  [x] No double-barreled questions
  [x] No leading language
  [x] Balanced response scales
  [x] N/A options where appropriate
  [x] Open-ended questions marked optional
  [x] Skip logic verified
  [x] Introduction text complete
  [x] Thank-you message included
  [x] Analysis framework delivered
  [x] File saved successfully
  [x] Notion database created (if requested)
```
