generate-codebook

コードブック生成スキル

未加工の表形式データセットを、構造化された引用可能なデータ辞書（コードブック）に変換します。これは辞書優先ワークフローの生成側です。/define-variables と辞書優先 QC が後で利用する成果物を生成します。分布、型、欠損状況は観察可能で、付属スクリプトがプロファイルします。一方、コード値の意味（fatty_liver_grade = 0）はデータからは観察できず、正式なデータ辞書にのみ記載されています。生成するのはコードブックであり、出力を確認します。コード値の意味を創作してはいけません。

決定論的スクリプト

列の内容を記憶に頼って説明するのではなく、付属のプロファイラーを実行してください。

python "${CLAUDE_SKILL_DIR}/scripts/generate_codebook.py" data.csv --out-dir .

.csv/.tsv/.xlsx/.parquet/.dta/.sas7bdat に対応しています。フラグ：--max-levels N （カテゴリ判定の上限、既定値は 20）、--json-only、--md-only。スクリプトは pandas のみを使用し、ローカルで実行され、データを外部に送信することはありません。

ワークフロー

ステップ 1：プロファイル（決定論的）

データセットに対して generate_codebook.py を実行します。codebook.json（機械可読形式）と codebook.md（レビュー用テーブル）を出力し、各変数について、役割 （id／連続値／カテゴリ／二値／日付／テキスト）、dtype、欠損状況、ユニーク値数、各水準の頻度または分位点の要約、および needs_dictionary フラグを報告します。

ステップ 2：研究者とレビューする（ゲート）

出力を解釈する前に ${CLAUDE_SKILL_DIR}/references/codebook_schema.md（codebook.json のスキーマ、役割推定のヒューリスティクス、needs_dictionary のルール）を読みます。codebook.md を提示し、内容をユーザーと一緒に確認します。ゲート： 役割の推定はヒューリスティックであるため、ユーザーに推定された役割を確認してもらいます（例：整数でコード化された尺度が連続値と誤判定された場合や、id 列の場合）。ユーザーが役割の割り当てを承認するまで、定義作業に進んではいけません。

ステップ 3：[NEEDS DICTIONARY] 項目を解決する（ゲート）

needs_dictionary: true とフラグ付けされた各変数について、正式な情報源がなければ水準コードを解釈できません。ゲート： 実際のデータ辞書に記載された各コードの意味（ファイル／シート／行）を提示するか、そのような辞書が存在しないことを確認するようユーザーに依頼します。label、units、および水準ごとの意味は、その情報源からのみコードブックに記入し、ファイル > シート > 行を引用します。推測で記入してはいけません。ユーザーが情報を提示できない場合は、[NEEDS DICTIONARY] マーカーを残し、削除してはいけません。

例：あるコホートファイルでは、sex（水準 1/2）と fatty_liver_grade（0..4）は水準が数字コードのみなのでフラグ付けされます。一方、smoking_status（never/former/current）はフラグ付けされません。「通常はそういうコードだから」という理由で、sex: 1 = male と書いてはいけません。辞書を参照できない場合は、フラグを残します。

ステップ 4：引き継ぐ

完成した codebook.json は、/define-variables （操作的定義）の入力辞書となり、辞書優先 QC の引用元となります。ゲート： 下流の分析でコードブックを正式な情報源として扱う前に、未解決の needs_dictionary フラグが残っていないことをユーザーに確認します。

コードブックを外部と共有する前に、生データに対して /deidentify を実行してください。データのクリーニングや変換には /clean-data を使用します。

既知の制限

• 数字ではなく、3 文字を超えるコード（C50.9、S001 など）はコードとして認識されないため、その列には needs_dictionary のフラグが付けられません。
• 異なる値が --max-levels より多い整数コード列は continuous に分類され、フラグが付けられません。このような列はステップ 2 の役割レビューで検出します。
• 数字を文字列で保持する text 列も同様です。数値（45、88）は測定値として読み取られるため、文字列としてエクスポートされた整数コードの値が --max-levels より多い場合、フラグは付けられません。

出力形式

codebook.json（スキーマは references 内）と codebook.md（「Columns requiring dictionary lookup」セクションを含むレビュー用テーブル）。件数 （行数、列数、needs_dictionary_count）をチャットで要約し、JSON 全体を貼り付けないでください。