/rosetta-stone-mapping-rules

name: rosetta-stone-mapping-rules
description: |
  The rules for mapping a Narrative dataset's columns to Rosetta Stone
  attributes: choosing the attribute, mapping the source of a derivation,
  value_mapping vs object_mapping, discriminators, validating each
  expression with NQL, and scoring confidence. No flow of its own; the
  skills that generate or infer mappings read it.
  Use when: another skill tells you to apply the mapping rules, "which
  Rosetta Stone attribute should this column map to", "is this mapping
  expression right".
  (narrative-common)
license: MIT
compatibility: >-
  Requires the narrative-mcp MCP server. Recommends the
  narrative-knowledge-base MCP server. Portable to any
  agentskills.io-compliant harness.
metadata:
  version: 0.1.0
  narrative:
    requires:
      skills:
        - narrative-common:find-attribute
      mcp-servers:
        - narrative-mcp
      mcp-tools:
        - narrative_attributes_describe
        - narrative_nql_validate
    recommends:
      mcp-servers:
        - narrative-knowledge-base
      mcp-tools:
        - narrative_derivations_describe
        - search_narrative_i_o_knowledge_base
        - query_docs_filesystem_narrative_i_o_knowledge_base

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Rosetta Stone Mapping Rules

Persona

You are a data quality engineer who treats Rosetta Stone mappings as a contract between a source dataset and the normalized identity graph. You never hallucinate a Rosetta Stone attribute id, never propose a mapping from a column name in isolation, and never emit an expression that has not passed `narrative_nql_validate`.

How to use this skill

These are the rules for turning a dataset's columns into mappings. The skill that sent you here owns the flow: how it reads the dataset, and how it presents or returns the mappings. Apply sections 1-4 to each column cluster, using the schema, sample rows and column stats that skill gathered.

When the platform-data tools aren't enough — e.g., you need official guidance on Rosetta Stone confidence scoring, the normalization model, or an NQL function/operator reference — consult the `narrative-knowledge-base` MCP server. See [`references/KB_RESEARCH.md`](references/KB_RESEARCH.md) for the recommended query patterns.

1. Find candidate Rosetta Stone attributes

Identify the column clusters that should resolve to attributes (individual columns for primitive mappings, groups like `{type, value}` or `{first_name, last_name}` for object mappings — see section 2).

For each cluster, delegate the catalog lookup to `/find-attribute`:

> `/find-attribute --phrase "<column semantic, e.g. 'email identifier'>" --no-confirm`

Fire **one `/find-attribute` invocation per semantic cluster in parallel** — the calls are independent, and parallelism is materially faster than serializing them. The skill owns its own search + paginate + batched-describe internally; you do not need to call `narrative_attributes_search` or `narrative_attributes_describe` yourself for the candidate-discovery step.

Each `/find-attribute` call returns a structured result:

attribute_id: <id>
display_name: <name>
schema:
  - { name: <column>, type: <type>, enum: [<values>] | null }
  - …
confidence: high | medium | low
match_reason: <one-line>
alternatives:
  - { attribute_id: <id>, display_name: <name>, why: <one-line> }
  - …

The `schema` field is the contract you need for section 2 — it includes type (primitive vs object), property paths (for object attributes — e.g., `type`, `value`, `context.source`), enum constraints (non-null `enum` array), and required vs optional flags. This is the **only** way to learn that detail; do NOT guess attribute IDs from memory or reason from search snippets.

When `confidence: low` or when `alternatives` cluster within 1-2 ranking points, treat all close candidates as in-play for that cluster and let sections 2 and 3 discriminate.

When you already know the target attribute ID (it was named explicitly, or you are checking an existing mapping), skip `/find-attribute` and call `narrative_attributes_describe(attribute_ids: [<id>, ...])` directly — describing a known ID does not need the search + ranking machinery.

Map every attribute the column holds

A column can hold several attributes. Each attribute is queried on its own, and a dataset that isn't mapped to one doesn't answer queries for it unless a derivation rule fills it in. So map every attribute whose description and enum the values meet, on the rows where they meet it. Some of the shapes this takes:

• **Parts of one value.** A `geo_location` of `US>TX>623` holds a

country, a state and a DMA: map `iso_3166_1_country`, `usps_state_abbreviation` and `designated_market_area`.

• **The same value, two attributes.** A `sex` column of `M`/`F` fits

both `hl7_gender` and `iab_gender`, and no rule derives one from the other: map both.

• **The same value on a subset of rows.** `state` ("a state or region

within a country") takes the second part from every row (`TX`, `ON`, `H9`). `usps_state_abbreviation` takes it from the `US` rows only, and no rule derives one from the other, so map both:

CASE WHEN geo_location LIKE 'US>%'
  THEN SUBSTRING_INDEX(SUBSTRING_INDEX(geo_location, '>', 2), '>', -1) END

Leaving out the rows that don't hold an attribute isn't filtering (see "Transform values; don't filter them"). A value on a `US` row that the enum doesn't list, such as `AE`, stays.

Each mapping has to be right on its own: an attribute the values only loosely match is a wrong mapping, not an extra one. And when a derivation rule reaches an attribute from another mapping, the rule covers it (next section).

Map the source of a derivation, not what it derives

Derivation rules compute one attribute from another, up to three rules deep. A dataset mapped to `raw_email` also answers queries for `normalized_em