Severity: high — the single biggest onboarding friction in this run.
What happened
The guide names questions.jsonl / respondents.jsonl / answers.jsonl but never specifies their fields, and question|respondent|answer import --help show only --survey/--path. I had to read survey_commands.py / cli.py to learn:
- question:
question_name, question_type (multiple_choice is the only closed/eligible type — probability_jobs.py:65, twin_jobs.py:434), question_options, role, source{raw_id,note}, option_labels.
- answer:
respondent_id, question, and answer or missing_code; answer must be in question_options when that list is non-empty or the row is quarantined (survey_commands.py:cmd_answer_import, cli.py:validate_answer).
- respondent:
respondent_id, weight, metadata, source.
- Undocumented:
source.known_options is used as the context option list when question_options is empty (cli.py:context_question_options).
Suggested fix
Add zwill guide show import-format (and expand the import --help) with the full per-file schema, the rank-item and multi-select conventions, the option-validation rule, and a copy-pasteable example row for each file.
Found while building a digital-twin validation for a 33-respondent SMB survey (smb.csv) end-to-end via zwill guide (survey → import → commit → one-shot marginals → twin-probability job → twin-validate → report). File/line refs are from zwill/ at that checkout.
Severity: high — the single biggest onboarding friction in this run.
What happened
The guide names
questions.jsonl/respondents.jsonl/answers.jsonlbut never specifies their fields, andquestion|respondent|answer import --helpshow only--survey/--path. I had to readsurvey_commands.py/cli.pyto learn:question_name,question_type(multiple_choiceis the only closed/eligible type —probability_jobs.py:65,twin_jobs.py:434),question_options,role,source{raw_id,note},option_labels.respondent_id,question, andanswerormissing_code;answermust be inquestion_optionswhen that list is non-empty or the row is quarantined (survey_commands.py:cmd_answer_import,cli.py:validate_answer).respondent_id,weight,metadata,source.source.known_optionsis used as the context option list whenquestion_optionsis empty (cli.py:context_question_options).Suggested fix
Add
zwill guide show import-format(and expand the import--help) with the full per-file schema, the rank-item and multi-select conventions, the option-validation rule, and a copy-pasteable example row for each file.Found while building a digital-twin validation for a 33-respondent SMB survey (
smb.csv) end-to-end viazwill guide(survey → import → commit → one-shot marginals → twin-probability job →twin-validate→ report). File/line refs are fromzwill/at that checkout.