---
name: codebook
description: Auto-generates a Markdown codebook from a dataset (CSV, DTA, Excel, Parquet) with types and summary statistics. Use when documenting variables.
argument-hint: <path to dataset>
allowed-tools: Bash, Read, Write, Glob, Grep
---

# Generate Variable Codebook

Auto-generate a Markdown codebook documenting all variables in a dataset.

## Arguments

- `$ARGUMENTS` — path to a dataset file (e.g., `data/rawData/sample_data.csv`, `data/panel.dta`)

## Steps

1. Determine the file format from the extension:
   - `.csv` — read with pandas `read_csv`
   - `.dta` — read with pandas `read_stata`
   - `.xlsx` / `.xls` — read with pandas `read_excel`
   - `.parquet` — read with pandas `read_parquet`
   - Other formats: ask the user how to load it

2. Load the dataset using `uv run python` and extract metadata for each variable:
   - Variable name
   - Data type (numeric, string, categorical, datetime)
   - Non-missing count and missing count
   - Number of unique values
   - For numeric variables: min, max, mean, median, standard deviation
   - For categorical/string variables: top 5 most frequent values with counts
   - For datetime variables: min and max date

3. Generate a Markdown codebook with:
   - **Header:** Dataset name, file path, number of observations, number of variables, date generated
   - **Summary table:** Variable name | Type | Non-missing | Unique | Description (placeholder)
   - **Detailed sections per variable:** Full statistics and a `[FILL: description]` placeholder for the user to add a human-readable description

4. Derive the output filename from the dataset name:
   - `data/rawData/sample_data.csv` → `references/sample-data-codebook.md`

5. Save to `references/<dataset-name>-codebook.md`

6. Report the file path and the number of variables documented.

## Error handling

- If the file does not exist, report the error and suggest checking the path.
- If the file cannot be read (corrupt, unsupported format), report the error and ask for guidance.
- Never modify the source data file. This command is read-only with respect to data.