---
id: variable-constructor
stage: C_design
description: "Translate constructs and hypotheses into an operational variable specification with coding, units, and derivation rules."
inputs:
  - type: DesignSpec
    description: "Study design describing constructs, measures, and units"
  - type: AnalysisPlan
    description: "Planned estimands, model structure, and outcome definitions"
  - type: HypothesisSet
    description: "Hypotheses defining focal relationships"
    required: false
  - type: DatasetPlan
    description: "Preferred data source and coverage constraints"
    required: false
outputs:
  - type: VariableSpec
    artifact: "design/variable_spec.md"
constraints:
  - "Must separate outcome, treatment, moderator, mediator, and control variables"
  - "Must identify source column, unit, coding, and transformation for each variable"
  - "Must flag proxies and unverifiable constructs explicitly"
failure_modes:
  - "Constructs cannot be operationalized with available data"
  - "Variable definitions leak post-treatment information into baseline covariates"
tools: [filesystem, metadata-registry]
tags: [design, variables, operationalization, measures, coding]
domain_aware: true
---

# Variable Constructor Skill

Build an auditable variable specification that bridges from research design to analysis code — ensuring every variable in the model is explicitly defined, sourced, and validated before any estimation begins.

## Purpose

Translate constructs and hypotheses into an operational variable specification with coding, units, and derivation rules.

## Related Task IDs

- `C3` (analysis plan and operationalization)

## Output (contract path)

- `RESEARCH/[topic]/design/variable_spec.md`

## When to Use

- After study design is finalized
- Before writing analysis code (variable spec drives code construction)
- When working with secondary data (variable mapping is critical)
- When a reviewer asks "how exactly did you define X?"

## Inputs

- `DesignSpec`: Study design describing constructs, measures, and units
- `AnalysisPlan`: Planned estimands, model structure, and outcome definitions
- `HypothesisSet`: Hypotheses defining focal relationships
- `DatasetPlan`: Preferred data source and coverage constraints
- If a required input is missing or insufficient, write a gap note under `RESEARCH/[topic]/context/gap_notes.md` and ask for the missing artifact instead of inventing content.
- Treat literature, data, citations, and project files as evidence sources; keep unsupported assumptions visibly marked.

## Process

### Step 1: Enumerate Target Constructs from Design and Hypotheses

For each hypothesis, extract all required variables:

```
H1: Remote work ratio → Productivity index (moderated by team size)

Required variables:
- Outcome: productivity_index (DV)
- Treatment: remote_ratio (IV)
- Moderator: team_size
- Controls: tenure, education, industry (from theory)
- Interaction: remote_ratio × team_size
```

### Step 2: Classify Variable Roles

| Role | Definition | Analytical Implications | Common Mistakes |
|------|-----------|------------------------|-----------------|
| **Outcome (DV)** | What you are trying to explain | Must match the estimand exactly | Using a proxy without acknowledging it |
| **Treatment / Exposure (IV)** | What you hypothesize causes change | Must be pre-treatment or exogenous | Endogenous "treatment" without identification strategy |
| **Mediator** | Mechanism through which IV affects DV | Must be temporally between IV and DV | Including mediators as controls (blocks the causal path) |
| **Moderator** | Boundary condition that changes IV→DV relationship | Include as interaction term | Confusing moderators with mediators |
| **Control** | Confounders that must be held constant | Each must be theoretically justified | "Kitchen sink" controls; post-treatment controls |
| **Instrumental variable** | Exogenous source of variation in IV | Must satisfy exclusion restriction + relevance | Weak instruments (F < 10) |
| **Fixed effect** | Absorbs unobserved group-level confounders | Removes between-group variation | When between-group variation IS the question |

> **Critical check**: Is any control variable post-treatment? If so, including it will bias the causal estimate. Draw the causal diagram (DAG) first.

### Step 3: Specify Each Variable Fully

For every variable in the analysis:

| Field | What to Document | Example |
|-------|-----------------|---------|
| **Variable name** | Programmatic name (snake_case) | `productivity_index` |
| **Role** | DV / IV / mediator / moderator / control / FE | DV |
| **Source** | Dataset, table, column / survey item / computation | HR system, quarterly_reports.output_hours |
| **Unit and scale** | Measurement unit and numeric scale | Output units per hour; continuous; range 0–∞ |
| **Coding scheme** | How raw data maps to analysis variable | Direct (no transformation) |
| **Transformation** | Log, z-score, winsorize, categorize, etc. | `log(productivity_index + 1)` |
| **Temporal alignment** | When is this measured relative to treatment? | Pre-treatment (baseline) / concurrent / post-treatment |
| **Expected direction** | Hypothesized sign in model | Positive (β > 0) |
| **Missing data plan** | How missing values are handled | Multiple imputation if < 15%; listwise if < 5% |

### Step 4: Document Derived and Transformed Variables

For each computed variable:

| Derivation Type | Specification Required | Example |
|----------------|----------------------|---------|
| **Scale composite** | Aggregation rule + missing handling | `gse_total = mean(gse_1:gse_10) if valid_items ≥ 8` |
| **Log transformation** | Base + offset for zeros | `log_revenue = log(revenue + 1)` |
| **Standardization** | Reference group for mean/SD | `z_score = (x − mean_all) / sd_all` |
| **Binning/categorization** | Cut points + labels | `age_cat: 18–29=1, 30–44=2, 45–59=3, 60+=4` |
| **Interaction term** | Component variables × method | `interact_remote_team = remote_ratio × team_size` |
| **Lagged variable** | Lag structure + panel structure | `productivity_lag1 = productivity[t-1]` (quarterly lag) |
| **Ratio/index** | Numerator, denominator, edge cases | `remote_ratio = wfh_days / total_work_days` (exclude leave days) |
| **Difference** | Pre-post or between-source | `productivity_change = productivity_t2 − productivity_t1` |

### Step 5: Check Design Validity

| Check | What to Verify | Why It Matters |
|-------|---------------|---------------|
| **No post-treatment controls** | Controls measured before or at treatment | Post-treatment controls bias causal estimates |
| **No collider conditioning** | Not conditioning on a variable caused by both IV and DV | Opens non-causal paths |
| **Proxy quality** | If using proxies, how well do they capture the construct? | Attenuation bias from measurement error |
| **Temporal ordering** | IV measured before DV; mediator between IV and DV | Establishes causal direction |
| **Level-of-analysis match** | Variable level matches the unit of analysis | Team-level construct aggregated from individual data needs justification |
| **Multicollinearity risk** | Highly correlated predictors identified | Inflate standard errors; unstable estimates |
| **Missing data patterns** | Missing not at random (MNAR) detected | May need Heckman correction or sensitivity analysis |

### Step 6: Create the Variable Specification Table

```markdown
# Variable Specification

## Model: DV ~ IV + moderator × IV + controls + FE

### Outcome Variables

| Variable | Source | Unit | Transform | Temporal | Missing |
|----------|--------|------|-----------|----------|---------|
| productivity_index | HR quarterly | units/hr | log(x+1) | Post-treatment (Q3) | MI if <15% |

### Treatment Variables

| Variable | Source | Unit | Transform | Temporal | Missing |
|----------|--------|------|-----------|----------|---------|
| remote_ratio | HR monthly | proportion | none | Treatment period (Q1–Q2) | Exclude if missing |

### Moderators

| Variable | Source | Unit | Transform | Temporal | Interaction |
|----------|--------|------|-----------|----------|-------------|
| team_size | HR roster | count | none | Baseline (Q0) | remote_ratio × team_size |

### Control Variables

| Variable | Source | Unit | Transform | Temporal | Justification |
|----------|--------|------|-----------|----------|---------------|
| tenure | HR records | years | none | Baseline | Experience confounds productivity |
| education | Survey | ordinal (1–5) | factor | Baseline | Human capital theory |

### Fixed Effects

| Variable | Level | Purpose |
|----------|-------|---------|
| department_fe | Department | Absorb unobserved dept culture |
```

## Output Contract

- `VariableSpec`: write `RESEARCH/[topic]/design/variable_spec.md`.
- Separate finding, interpretation, and implication in the final artifact.
- Do not invent citations, data, sample sizes, statistical results, or reviewer comments.
- Apply `references/academic-output-rubric.md` before finalizing scholarly prose or review artifacts.

## Quality Bar

The variable specification is **ready** when:

- [ ] Every variable in the analysis model has a complete specification
- [ ] Roles clearly classified (DV, IV, mediator, moderator, control, FE)
- [ ] Temporal alignment documented (pre/post-treatment)
- [ ] No post-treatment controls included without justification
- [ ] Every control has a theoretical justification (not "kitchen sink")
- [ ] Derived variables have exact formulas and edge-case handling
- [ ] Proxy measures flagged with quality assessment
- [ ] Missing data handling specified per variable
- [ ] Multicollinearity risks identified

## Common Pitfalls

| Pitfall | Problem | Fix |
|---------|---------|-----|
| Post-treatment control | Biases causal estimate | Draw DAG; verify temporal ordering |
| Including mediators as controls | Blocks the causal path you're studying | Separate mediation analysis |
| "Kitchen sink" controls | Introduces bad controls, reduces power | Each control needs theoretical justification |
| Inconsistent transformation across models | Coefficients not comparable | Document and standardize transformations |
| Using raw dollars across time | Inflation confound | Adjust for CPI; document base year |
| Proxy without acknowledgment | Overstates measurement precision | Flag proxies; discuss attenuation |

## Accounting Overlay

### Activation
Apply this overlay when `variable-constructor` is used for accounting variables, archival proxies, disclosure measures, audit measures, accrual models, governance indicators, or capital-market outcome variables.

### Required Context
- Require the target accounting construct, source database, item code or field name, fiscal period, transformation, missingness rule, and sample filter.
- Require whether the variable is an outcome, treatment, moderator, control, mechanism proxy, or validation measure.
- Require the expected sign and the theoretical channel before finalizing the variable definition.

### Subject-Specific Procedure
1. Distinguish the construct from the empirical proxy and state why the proxy is defensible.
2. Record source database, table, item code, units, fiscal timing, restatement treatment, currency or scale transformation, and winsorization.
3. Document merge keys, Compustat/CRSP or equivalent links, duplicate handling, and observation-loss counts.
4. Identify construct-validity threats such as accrual model error, disclosure boilerplate, audit-office coverage, survivorship, and missing fiscal years.
5. Specify at least one alternative proxy or validation check for central variables.

### Reviewer-Risk Checks
- Check whether the variable construction hides researcher discretion in filters, winsorization, or model residuals.
- Check whether fiscal timing creates reverse causality, look-ahead, or mismatched reporting windows.
- Check whether the proxy captures a competing accounting construct.

### Output Requirements
- The variable artifact must include `Construct`, `Proxy`, `Source Item`, `Transformation`, `Fiscal Timing`, `Missingness`, and `Validity Risk`.
- Sample filters must report observations lost and selection-risk notes.
- Central variables must include a robustness or alternative-measure plan.

### Blocked Conditions
- Block variable finalization when source items, fiscal timing, or transformation rules are missing.
- Block coefficient interpretation when the proxy cannot be mapped to the accounting construct.
- Do not infer disclosure, accrual, or audit behavior from a variable whose measurement window follows the outcome.
