/generate-rosetta-stone-mappings

name: generate-rosetta-stone-mappings
description: |
  Generate, evaluate, and improve Rosetta Stone attribute mappings for
  a Narrative dataset.
  Use when: "map this dataset to Rosetta Stone", "suggest normalized
  attributes for dataset N", "evaluate the mappings on dataset N", "why
  is this mapping low confidence", "fix this expression", "improve this
  NQL mapping expression".
  (narrative-common)
license: MIT
compatibility: >-
  Requires the narrative-mcp MCP server. Recommends AskUserQuestion (a
  Claude Code primitive; prose fallback in references/HARNESS_FALLBACK.md)
  and the narrative-knowledge-base MCP server. Portable to any
  agentskills.io-compliant harness via the documented fallbacks.
metadata:
  version: 0.5.3
  narrative:
    args:
      - name: "<free-text>"
        required: false
        description: >-
          Natural-language intent naming the source dataset and what to map
          (e.g., "map dataset 12345 to Rosetta Stone", "evaluate the mappings
          on dataset N"). This skill takes no flags; it resolves the dataset
          and gathers context interactively. With no arguments, it asks which
          dataset to map.
    requires:
      skills:
        - narrative-common:profile-dataset
        - narrative-common:find-attribute
      mcp-servers:
        - narrative-mcp
      mcp-tools:
        - narrative_context_get
        - narrative_context_search_companies
        - narrative_context_set_company
        - narrative_datasets_search
        - narrative_datasets_describe
        - narrative_attributes_describe
        - narrative_nql_validate
        - narrative_nql_execute
        - narrative_jobs_search
        - narrative_jobs_describe
    recommends:
      skills:
        - narrative-common:apply-rosetta-stone-mappings
      tools:
        - AskUserQuestion
      mcp-servers:
        - narrative-knowledge-base
      mcp-tools:
        - 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 -->

Generate Rosetta Stone Mappings

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 optimize for:

1. Evidence — every mapping is grounded in schema, sample rows, and column stats from `narrative-mcp`; column names alone are not enough. 2. Validity — every NQL expression is server-validated before it is suggested. 3. Calibrated confidence — low-confidence mappings are surfaced as low-confidence, not promoted to fit a quota.

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`.

Output rules

**Don't surface `_nio_*` field names to the user.** Columns and fields whose names start with `_nio_` (e.g., `_nio_last_modified_at`, `_nio_sample_128`) are platform-managed internals. Handle them silently as this skill instructs — filtering, skipping, or accepting auto-generated mappings — but do not name them in user-facing output: lists, tables, summaries, warnings, status messages, or final responses. Refer to them generically ("platform-managed columns", "reserved internal fields") if you need to acknowledge them at all.

Exception: if the user expressly asks about `_nio_*` fields, answer normally.

Overview

Map columns from a Narrative source dataset to Rosetta Stone attributes via progressive calls to the `narrative-mcp` server. Fetch only the schema slice, sample rows, column stats, and attribute definitions you need for each decision, and validate every expression with `narrative_nql_validate` (and optionally `narrative_nql_execute`) before suggesting it.

Without this discipline an agent will either (a) write mappings from column names alone, (b) hallucinate Rosetta Stone attribute IDs, or (c) emit SQL that fails NQL validation. Don't.

When the platform-data tools above 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` for the recommended query patterns.

When to use

Triggers:

• "Map this dataset to Rosetta Stone" / "suggest normalized attributes for dataset N"
• "Why is mapping X low confidence?" / "evaluate the mappings on dataset N"
• "Fix this mapping expression" / "improve this NQL expression to handle X"
• "Make a value_mapping / object_mapping for this column"
• Any work involving `narrative.rosetta_stone."<attribute>"` and a specific source dataset

Do NOT use for:

• Pure NQL query authoring with no mapping intent — go to NQL skills.
• Custom-attribute *creation* — call this skill first to confirm no

Rosetta Stone attribute already covers the column, then hand off.

Procedure

Run these steps in order. Steps 1-3 are mandatory context-gathering; steps 4-6 run per column being mapped; steps 7-8 finalize.

**Parallelize where the calls are independent.** Most steps below have fan-out points — multiple `/find-attribute` invocations (one per semantic cluster), a batch of `narrative_attributes_describe` IDs when reconfirming known attributes, a batch of `narrative_nql_validate` expressions. Issue these as concurrent tool calls in a single turn instead of looping serially. For very wide datasets (50+ mappable columns), consider spawning a sub-agent per column cluster so each one owns its own find → validate loop and only the final scoring is reconciled at the parent.

1. Pin the company / context

Most Narrative work is scoped to a company. Before any dataset, attribute, or workflow call:

narrative_context_get  → check the active company

If no company is set, or the user named a different one:

narrative_context_search_companies(search_te