Questionnaire Codebook Maker

Problem to solve

In psychology, education, public-health, and social-science projects, questionnaire items, dimensions, variable names, reverse scoring, and data-entry rules often remain scattered across documents, spreadsheets, or chat logs. Before analysis, researchers still need to check whether item_id is unique, whether dimension is missing, whether response_range is consistent, and whether reverse items should use 6 - original or 4 - original. Without a consistent codebook, downstream work in Excel, SPSS, R, or Mplus can quickly produce variable-name conflicts, inconsistent scoring, and opaque missing-value handling.

How it works

This skill organizes a questionnaire into an analysis-ready codebook. Its core output is a copy-ready TSV table with columns such as variable, item_id, dimension, item_text, response_range, reverse_scored, scoring_note, and missing_rule. It generates short, readable variable names in the style of dep_01 or anx_02, using lowercase letters, numbers, and underscores, and avoids spaces, Chinese punctuation, and overly long names. For reverse scoring, it applies the general formula reversed_score = min + max - original_score, with common examples such as 6 - original for 1–5 scales and 4 - original for 0–4 scales. If missing-value rules are not supplied, it suggests a transparent rule, such as calculating a dimension mean only when at least 80% of that dimension's items are non-missing, and it does not silently impute values. The optional helper script scripts/make_codebook.py can convert a simple CSV item file into a Markdown codebook and a TSV variable map using only the Python standard library.

Boundaries

It is useful for turning messy scale descriptions into structured tables, but it should not invent item wording, clinical cutoffs, or scale-manual interpretations. Uncertain reverse-scoring decisions should be marked as uncertain, and item-level reverse scoring, dimension scoring, and total-score calculation should be kept distinct.