data-map

Skill: Data Map

Purpose

Answer the broadest possible question — "tell me about this data" — with the broadest substantive answer: cross-table health, relationships, date alignment, and an opening analytical thread. This is first-contact dataset exploration, not a schema dump and not a steering question.

When to Fire

Fires on dataset-wide open questions:

• "tell me about this data / the data / this dataset / the dataset"
• "what's in here / what's in this data / what's in the data"
• "give me an overview / give me the map / map out the data"
• "what do I have / what do we have here"
• "what does this data look like / show me what we've got"
• Any open question that references the dataset as a whole

Does NOT fire when:

• The question names a specific table → use data-quality-check
• User invoked /explore or is mid-exploration within an already-mapped dataset → use explore
• User invoked /data or /data {table} → use data-inspect (schema-only)
• User invoked /run-pipeline or a specific analysis → run the pipeline

Fires regardless of:

• Whether the dataset was recently profiled (data-profiling populates .knowledge/, this skill produces a live report)
• Whether the user explicitly asked for DQ (it's implicit in "tell me about")

Instructions

Step 0 — Resolve active dataset

1. Read .knowledge/active.yaml to get active_dataset. If missing, halt and tell the user to run /connect-data or /setup.
2. Read .knowledge/datasets/{active}/manifest.yaml for connection type and local paths.
3. Read .knowledge/datasets/{active}/schema.md for table list and column types.
4. Read .knowledge/datasets/{active}/quirks.md to surface known gotchas inline.
5. Connect through ConnectionManager (helpers/data/connection_manager.py) and announce which source is live in one line.

Step 1 — Table inventory and PK health

For every table in schema.md, run:

SELECT
  COUNT(*)                                       AS row_count,
  COUNT(DISTINCT {pk_col})                       AS distinct_pk,
  COUNT(*) - COUNT(DISTINCT {pk_col})            AS pk_dupes,
  SUM(CASE WHEN {pk_col} IS NULL THEN 1 ELSE 0 END) AS pk_nulls
FROM {schema}.{table};