Cliente sube CSV/XLSX/XLS/TSV/JSON
        ↓
data-intake-normalizer  ← SIEMPRE primero
        ↓
validation_report.json
  OK   → ejecutar skill downstream con data_normalized.csv
  WARN → mostrar advertencias, ejecutar con caveats
  BLOCK → mostrar errores, solicitar corrección, ofrecer template

También activa cuando el usuario pide:

"Dame la plantilla para [skill]"
"¿Qué formato necesita el archivo?"
"El script falla con mi CSV"

Schemas por skill — columnas requeridas / opcionales

Lee references/schemas.md para el schema completo de cada skill. Resumen ejecutivo:

Skill destino	Columnas requeridas	Columnas opcionales clave
`customer-segmentation-clustering`	`customer_id`, `transaction_date`, `amount`	`category`, `brand`, `channel`
`customer-lifetime-value`	`customer_id`, `period`, `revenue`, `cost`	`retention_flag`, `channel`, `cohort`
`survival-analysis-marketing`	`customer_id`, `event_date`, `censored`	`discount`, `emails_sent`, `segment`
`response-uplift-modeling`	`customer_id`, `treatment`, `response`	`score`, `segment`, `spend`, `ltv`
`market-basket-analysis`	`transaction_id`, `item_id`	`amount`, `category`, `timestamp`
`price-demand-optimization`	`price`, `quantity`	`period`, `competitor_price`, `promotion`
`recommender-systems`	`user_id`, `item_id`, `rating`	`timestamp`, `context`, `category`
`mmm-modeling`	`date`, `kpi` + ≥1 `spend_[channel]`	`price_index`, `promo`, `seasonality`
`audience-segmentation-brief`	`customer_id`, `segment`, `ltv`	`channel`, `rfm_score`, `persona`
`media-routing-planner`	`channel`, `spend`, `impressions`, `conversions`	`cpm`, `cpa`, `roas`, `period`
`weekly-control-tower`	`date`, `kpi`, `actual`, `target`	`channel`, `campaign`, `segment`
`measurement-incrementality`	`date`, `group` (test/control), `kpi`	`spend`, `impressions`, `conversions`
`crm-journey-architect`	`customer_id`, `event`, `timestamp`	`channel`, `segment`, `value`
`scope-audit`	Texto libre (RFP/SOW) — no normalización	—
`margin-simulation`	`fee`, `fte_cost`, `vendor_cost`, `hours`	`segment`, `client`, `period`

Workflow

Step 1 — Detectar archivo

python scripts/schema_detector.py \
    --file /mnt/user-data/uploads/[filename] \
    --output results/detection.json

Output: { target_skill, confidence, detected_columns, file_info }

Step 2 — Mapear columnas

python scripts/column_mapper.py \
    --file /mnt/user-data/uploads/[filename] \
    --target-skill [skill_name] \
    --output results/column_map.json

Output: { mappings: { client_col → os_col }, unmapped, missing_required }

Step 3 — Normalizar tipos + encoding

python scripts/type_coercer.py \
    --file /mnt/user-data/uploads/[filename] \
    --column-map results/column_map.json \
    --output results/data_typed.csv

Handles: fechas (≥15 formatos), montos (comas, símbolos), encodings (UTF-8/latin-1/CP1252/UTF-16)

Step 4 — Manejar nulos

python scripts/null_handler.py \
    --file results/data_typed.csv \
    --target-skill [skill_name] \
    --output results/data_normalized.csv

Estrategias por columna: drop / median / mode / forward-fill / flag

Step 5 — Reporte de validación

python scripts/validation_report.py \
    --normalized results/data_normalized.csv \
    --target-skill [skill_name] \
    --column-map results/column_map.json \
    --output results/validation_report.json

Step 6 — Mostrar resultado al usuario

[show_widget] validation dashboard — siempre antes de ejecutar skill downstream

Generar plantilla (modo alternativo)

python scripts/template_generator.py \
    --skill [skill_name] \
    --output /mnt/user-data/outputs/template_[skill_name].xlsx

Niveles de validación

Nivel	Condición	Acción
`OK`	Todas las columnas requeridas presentes, tipos correctos, nulos < 5%	Ejecutar skill downstream
`WARN`	Columnas opcionales faltantes, nulos 5–20%, mapeo fuzzy aplicado	Ejecutar con caveats visibles
`BLOCK`	Columnas requeridas faltantes, nulos > 20% en columna crítica, encoding irrecuperable	Detener. Mostrar errores. Ofrecer plantilla.

Output format — Visualization First

Dashboard panels (ver references/intake_dashboard_template.html):

Status banner — OK / WARN / BLOCK con color
File info — filas, columnas, encoding, tamaño, skill detectado
Column mapping table — cliente col → OS col, con status por columna
Issues list — errores y advertencias con descripción accionable
Preview — primeras 5 filas del archivo normalizado
Next step — botón sendPrompt() al skill downstream si OK/WARN

Marketer Insights Layer

Siempre incluir después del dashboard:

Qué columnas se renombraron automáticamente y por qué
Qué nulos se imputaron con qué estrategia
Cuántas filas quedaron disponibles vs total original
Si hay BLOCK: mensaje claro + "Descarga la plantilla correcta" + botón

Reglas de orquestación (OS rules)

Rule #19: ALWAYS run data-intake-normalizer before any science skill
          when input is CSV/XLSX. BLOCK if validation_report = BLOCK.
Rule #20: If client provides data in Google Drive → use Google Drive MCP
          read directly (no upload needed), still run normalization.
Rule #21: If normalization fails 2+ times on same file → offer template
          download for that specific skill automatically.

Reference files

references/schemas.md — Schema completo por skill (columnas, tipos, constraints)
references/type_rules.md — Reglas de coerción por tipo de dato
references/null_strategies.md — Estrategia de imputación por columna y skill
references/intake_dashboard_template.html — Dashboard HTML; inject SKILL_DATA_JSON
templates/ — Plantillas XLSX pre-generadas por skill (generadas con template_generator.py)

data-intake-normalizer

Data Intake Normalizer

Cuándo activar