Survey Design Pack

We built this pack so you don't have to maintain fragile JSON schemas, reinvent sampling calculators, or debug expression logic every time your research team needs a new survey. If you are an engineer tasked with powering survey infrastructure, you know the pain of ad-hoc question design: double-barreled questions slip through, conditional branching breaks on edge cases, and statistical analysis scripts are written from scratch for every project, leading to inconsistent results.

This skill provides the full lifecycle management for survey design. It includes production-grade SurveyJS schemas, spectral validators for question quality, sampling strategy templates, and Python scripts for statistical analysis. It is designed for researchers conducting social science, market research, or academic studies who need reliability, not hacks.

The Fragility of Ad-Hoc Survey Logic

Most survey tools rely on JSON structures that are easy to break. When you define complex logic—matrix dynamics, conditional branching, or expression-based validation—you are essentially writing a mini-application inside a configuration file. Without a strict schema, typos in expression syntax like avgInArray or countInArray go undetected until runtime, causing the survey to crash or return silent errors.

We see teams spending hours debugging why a matrix question isn't rendering or why a skip logic branch is infinite. The problem isn't just technical; it's methodological. Questions often violate best practices for data quality. Double-barreled questions, leading language, and inconsistent scales introduce noise that no amount of post-hoc cleaning can fully remove. Without automated validation, you are relying on human review to catch structural flaws, and human review is slow and error-prone.

If you are also building user feedback loops, you might find the User Research Pack useful for closing the loop between survey data and actionable insights. But for the survey itself, you need a solid foundation.

The Hidden Costs of Bad Sampling and Biased Questions

Ignoring survey design quality has real consequences. Bad sampling leads to unrepresentative data, which invalidates your conclusions. According to the Standards and Guidelines for Statistical Surveys, agencies must develop a survey design that includes defining the target population and specifying the data collection method ^[1]. When you skip this step, you risk sampling bias that skews your entire study.

Bias is a constant threat in survey research. Reducing bias requires careful attention to question wording, respondent validation, and representing deviant cases ^[5]. A leading question can prime respondents to answer in a way that confirms your hypothesis, destroying the integrity of your data. The cost of this isn't just wasted time; it's lost credibility. If your stakeholders find out your survey was biased or your sampling was flawed, your results are dismissed.

Furthermore, the financial impact is significant. In market research, a flawed survey can lead to incorrect TAM/SAM/SOM estimates, causing misallocation of resources. If you need to integrate survey data with broader market analysis, the Market Research Pack can help you contextualize your findings, but only if your raw data is clean.

Best practices for survey research emphasize rigorous design, data collection, and analysis to produce the best possible survey ^[6]. Without tools to enforce these standards, you are left with guesswork. The UX Research Pack offers a complementary workflow for user testing, but it doesn't replace the need for a robust survey engine.

A Hypothetical Case: When Logic Breaks at Scale

Imagine a research team deploying a 50-question survey with conditional branching, matrix questions, and complex expression logic. They use a custom JSON schema that lacks strict validation. Halfway through distribution, they discover that a skip logic branch is causing respondents to see questions they shouldn't, leading to high drop-off rates.

The team scrambles to fix the JSON, but the fix introduces a new bug: a matrix question fails to render for a subset of users due to a type mismatch in the expression syntax. They spend three days debugging, losing valuable response time. Meanwhile, the sampling strategy was defined ad-hoc, without calculating the required sample size for the desired confidence level. The final dataset is small and biased, making statistical analysis unreliable.

A proper sampling design should cover primary units, sampling units, and sample size calculation ^[8]. Without this, the team is flying blind. In a public case study cited in research on survey methodology, teams that neglected sampling guidelines faced significant challenges in data approval and quality ^[8]. This hypothetical scenario mirrors real-world failures where technical debt in survey design leads to methodological errors.

If your team also needs to analyze the resulting data, the Data Analysis Pack can help with hypothesis testing and regression, but it won't save you from bad survey design.

What Changes Once the Pack Is Installed

With the Survey Design Pack installed, your survey lifecycle becomes deterministic and reliable. Here is what changes:

• Schema Validation: Every SurveyJS JSON file is validated against a strict JSON Schema definition. The validate-survey.py script checks for type errors, missing required fields, and invalid expression syntax. If the schema fails, the survey won't deploy. This catches bugs before they reach respondents.
• Question Quality Linting: The Spectral ruleset spectral.yaml lints your survey questions for double-barreled phrasing, leading language, and length violations. You get immediate feedback on question design, ensuring compliance with best practices for survey integrity ^[4].
• Sampling Strategy: The sampling-strategy.md template guides you through defining the population, selecting the method, and calculating sample size. You no longer guess; you follow a structured process that aligns with statistical standards ^[1].
• Statistical Analysis: The analyze-responses.py script simulates statistical analysis of survey responses, implementing expression logic like avgInArray and countInArray. This ensures your analysis code matches your survey logic, reducing discrepancies between design and output.
• Reporting: The reporting-template.md provides a consistent structure for reporting results, including methodology, confidence intervals, and limitations. This makes your reports professional and reproducible.
• Integration: The skill integrates seamlessly with SurveyJS, allowing you to use the survey-creator-config.ts for customization and persistence. You can also link your survey data to broader research workflows using the User Research Pack or Market Research Pack.

The result is a survey system that is auditable, consistent, and statistically sound. You spend less time debugging and more time gathering insights.

What's in the Survey Design Pack

This is a multi-file deliverable designed for production use. Every file serves a specific purpose in the survey lifecycle.

• skill.md — Orchestrator skill defining the survey lifecycle workflow, referencing all templates, validators, scripts, and references.
• templates/survey-schema.json — Production-grade SurveyJS JSON schema template with complex logic, matrix dynamics, expressions, and theme integration.
• templates/survey-creator-config.ts — TypeScript configuration for Survey Creator integration demonstrating property customization, instance handling, and persistence.
• templates/sampling-strategy.md — Structured template for defining sampling strategies, including population definition, method selection, and sample size calculation.
• templates/reporting-template.md — Markdown template for reporting survey results, including methodology, statistical analysis, confidence intervals, and limitations.
• scripts/validate-survey.py — Python script to validate SurveyJS JSON schemas against the JSON Schema definition, exiting non-zero on failure.
• scripts/analyze-responses.py — Python script to simulate statistical analysis of survey responses, implementing expression logic like avgInArray and countInArray.
• validators/schema/survey-schema.json — JSON Schema definition for validating SurveyJS JSON structure, types, and expression syntax patterns.
• validators/spectral/spectral.yaml — Spectral ruleset for linting survey question text, detecting double-barreled questions, leading questions, and length violations.
• references/survey-best-practices.md — Curated authoritative knowledge on survey methodology, question design, bias mitigation, length, and reporting standards.
• references/surveyjs-expressions.md — Canonical reference for SurveyJS expression syntax, operators, functions, and event handlers based on official documentation.
• examples/worked-example.json — Complete SurveyJS JSON example demonstrating complex scenarios, conditional logic, and matrix dynamics.
• examples/test-responses.json — Sample response data for testing the analysis script and validating expression logic.

Each component is tested and documented. The worked-example.json shows you how to use complex scenarios, and test-responses.json lets you verify your analysis pipeline before deployment.

Stop Guessing, Start Shipping

Your survey data is only as good as your design. Stop relying on fragile JSON and ad-hoc methods. Upgrade to Pro to install the Survey Design Pack and gain access to production-grade schemas, validators, and analysis tools. Ship surveys that are statistically sound, bias-minimized, and technically robust.

Install the skill and transform your survey workflow today.