Data Context Extractor

/data-context-extractor

Extract the tribal knowledge in a user's head (or team) about what their data actually means, and turn it into a durable data context document. The user is the data source: you interview them, listen for the knowledge that never gets written down, and deliver a structured reference they can reuse -- paste into future conversations, hand to new analysts, or keep as team documentation.

This skill is about capturing MEANING, not inspecting rows. If the user pastes a dataset and wants to understand it, that is explore-data. If they want conclusions from data, that is analyze-dataset. Use this skill when the deliverable is a knowledge document about their data.

Two Modes

1. Bootstrap: no context doc exists yet. Run the full interview and produce a complete document.
2. Iteration: the user pastes an existing context doc (or you built one earlier in the conversation) and wants to extend it -- a new domain, missing metrics, newly discovered gotchas. Ask targeted questions only about the gap, then deliver the updated document.

The Interview (Bootstrap Mode)

First, ask the user to describe their data landscape in their own words: what systems or tables exist, and which 3-5 tables or datasets analysts touch most often. If they can paste schema listings, column lists, or a few sample rows, use them to sharpen your questions -- but the interview works without them.

Then work through the five question areas below. Ask conversationally, a couple at a time, not as a form. The listening notes are the real skill: they tell you what to probe for in the answers.

1. Entity disambiguation (most important)

"When people here say 'user' or 'customer', what exactly do they mean? Are there different types?"

Listen for: multiple entity types (user vs account vs organization), the relationships between them (1:1, 1:many, many:many), and which ID fields link them. Most wrong analyses trace back to joining or counting the wrong entity.

2. Primary identifiers

"What is the main identifier for a customer/user/account? Are there multiple IDs for the same entity?"

Listen for: primary keys vs business keys, UUID vs integer IDs, legacy ID systems still lurking in old tables.

3. Key metrics

"What are the 2-3 metrics people ask about most? How is each one calculated, exactly?"

Listen for: exact formulas (ARR = monthly_revenue x 12), which tables and columns feed each metric, and time period conventions (trailing 7 days vs calendar month). Push past "revenue" to the precise definition -- gross or net, booked or recognized, which currency.

4. Data hygiene

"What should ALWAYS be filtered out? Test data, fraud, internal users?"

Listen for: standard exclusion conditions every query must include, flag columns (is_test, is_internal, is_fraud), and specific magic values (status = 'deleted').

5. Gotchas

"What mistakes do new analysts typically make with this data?"

Listen for: confusingly named columns, timezone traps, NULL-handling quirks, historical-vs-current-state tables, duplicated rows from pipeline retries. These answers are the highest-value content in the document -- an expert's scar tissue.

Interviewing Technique

• Ask follow-ups when an answer is vague. "We filter out test accounts" is not capturable knowledge; "WHERE is_internal = false AND email NOT LIKE '%@ourco.com'" is.
• When the user states a formula, restate it back precisely and ask them to confirm. Metric definitions are where paraphrasing silently corrupts the doc.
• Notice contradictions across answers (two different definitions of "active user") and surface them explicitly -- resolving those is often the most valuable thing the session produces.
• Do not exhaust every area in one pass. Capture what the user knows now; the document is designed to be iterated.

The Deliverable

Produce a single Markdown document as a chat artifact, structured so the user can paste it into any future data conversation:

# [Company/Team] Data Context

## Entities
For each entity: name, business definition, primary table/source,
ID field(s), relationships to other entities, standard exclusion filters.

## Metrics
For each metric: human-readable name, plain-English definition,
exact formula with column references, source table(s), caveats and edge cases.

## Standard Filters
The conditions every query should include, with the reason for each.

## Gotchas
Numbered list. Each entry: the trap, why it happens, what to do instead.

## Terminology
Company-specific terms and their precise meanings.

## Open Questions
Things the user was unsure about -- explicitly marked so the doc
does not present guesses as facts.

Only include sections the interview actually populated. An honest short document beats a padded template.

Quality Bar Before Delivering

• Every metric has an exact formula, not a paraphrase
• Entity relationships state cardinality and the joining ID
• Every exclusion filter states WHY it exists
• Gotchas are specific enough that a stranger would avoid the trap
• Anything the user hedged on is in Open Questions, not asserted as fact

Fences

• Exploring or profiling a dataset the user pasted: use explore-data.
• Running a full analysis to answer a business question: use analyze-dataset.
• This skill produces a knowledge document; it does not compute anything from data.

Usage

/data-context-extractor $ARGUMENTS