survey-analytics

Survey Analytics

This skill analyzes survey results.

It does not generate survey HTML. It consumes:

• a survey schema
• a survey answers dataset

Primary job

Take a validated survey schema plus answers and produce:

• one Excel workbook where columns are questions and rows are submissions
• per-question statistics and charts by question type
• cross-question or logic-driven analysis tables
• a machine-readable analysis JSON
• a human-readable insight report

Read these first

Before analyzing, read:

• ../../specs/analytics-input.md
• ../../specs/answer-storage.md
• ../../specs/submission-api.md
• ./references/metrics-model.md
• ./references/report-shape.md
• ./docs/OUTPUTS.md

Expected input

Preferred input:

• absolute path to a survey schema JSON file
• absolute path to an answers JSON or JSONL file

Also acceptable:

• inline schema JSON
• inline answers JSON
• a directory containing both schema and answers exports

Required execution mode

Do not stop at a prose-only analysis when local file execution is available.

Use the executable pipeline:

python3 <survey-analytics-root>/tools/analyze_survey_results.py \
  --schema /absolute/path/to/schema.json \
  --answers /absolute/path/to/answers.json \
  --out-dir /absolute/path/to/output-dir

When the user wants specific cross-question analysis, pass a config file:

python3 <survey-analytics-root>/tools/analyze_survey_results.py \
  --schema /absolute/path/to/schema.json \
  --answers /absolute/path/to/answers.json \
  --cross-config /absolute/path/to/cross-config.json \
  --out-dir /absolute/path/to/output-dir

The script generates:

• <name>.analysis.xlsx
• <name>.analysis.json
• <name>.analysis.md

If the user only asks for insights and does not want files, you may summarize the generated report instead of returning file contents.

Analysis rules

1. validate that every normalized answer document belongs to the provided surveyId
2. ignore malformed records, but report how many were excluded and why
3. compute distributions only from structurally valid answers
4. preserve question ids and option ids in intermediate reasoning
5. separate factual summary from interpretation
6. call out low sample size before making strong conclusions
7. do not invent respondent intent that is not grounded in the dataset
8. when schema logic exists, use it to infer finish-path or segment-level analysis when possible