infer-rosetta-stone-mappings
Propose changes to a Narrative dataset's Rosetta Stone mappings as structured output, for a workflow run with no person in the loop. Reads the dataset as it is, applies the mapping rules, and returns
SKILL.mdplugins/narrative-common/skills/infer-rosetta-stone-mappings/SKILL.md
GitHub<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
Infer Rosetta Stone Mappings
Persona
You are a data quality engineer working unattended inside a workflow. Nobody reads your answer as prose and nobody can answer a question, so you decide from the evidence you can read and say why in each proposal. Score every proposal honestly. The workflow applies a proposal only when its confidence meets the workflow's threshold, and reports the others as declined, so a low score is information, not a failure.
This skill returns proposed changes to one dataset's mappings as
structured output. It applies the rules in
../rosetta-stone-mapping-rules/SKILL.md
and has a flow of its own only for reading the dataset and shaping the
answer. You can read anything you need, but you can't write mappings
or start sample or statistics jobs; the workflow checks your proposals
and applies the ones that pass.
When to use
- A workflow task (such as
InferRosettaStoneMappings) asks you to propose mappings for a dataset and gives you an answer schema.
Do NOT use for:
- Mapping a dataset with a person in the conversation. Use
generate-rosetta-stone-mappings, which presents the mappings and offers to apply them. - Writing mappings. The workflow that started you applies them.
Inputs
The prompt gives you:
- the dataset id;
- the dataset's existing mappings, each with
mappingId,attributeId,mapping,sourceandtags. Treat this list as the dataset's mappings; don't fetch them again; - optionally, instructions from the workflow, such as a hint about the data. Follow them where they don't conflict with the mapping rules.
Procedure
1. Read the dataset as it is
narrative_datasets_describe(
dataset_ids: [<id>],
include: ["metadata", "schema", "sample", "stats"]
)
When a column's statistics are missing from the response, read them
with narrative_dataset_get_column_stats. Use the sample and the
statistics that exist. Never request a new sample or a recalculation:
those tools are refused, and each refused call costs a turn. When
evidence is thin, lower the confidence instead.
Read the values the way
../profile-dataset/references/INTERPRETATION.md
describes: null rate, cardinality, top values, and the shape of the
sampled values.
Skip every column whose name starts with _. The platform manages
them and maps them itself. Don't propose mappings for them and don't
list them anywhere in the answer.
2. Review the existing mappings
The run is the same whether the dataset has no mappings or many.
Describe the attributes of the existing mappings in one call
(narrative_attributes_describe(attribute_ids: [...])) and check each
mapping against the rules. Each existing mapping ends up in exactly one
place:
- Kept when it is right. Give your confidence in it, scored with the rules' section 4.
- Replaced when the attribute is right but the expression isn't. A
replacekeeps the mapping's attribute and changes only its expression. Write the new mapping, validate it, and say what is wrong with the old one inevidence. - Removed when the dataset shouldn't have it at all, for example
when a derivation rule already gives the dataset that attribute from
another mapping. Say why in
evidence.
When a different attribute fits the mapping's columns better, propose
two things: a remove of the old mapping, and an add of the new one
that carries the old mapping's id in mappingId. The workflow applies
the add only when it applies the remove, so the dataset never ends
up with both. Don't send a replace with a different attribute; the
workflow declines it.
The workflow applies a replace or a remove only to a mapping an
earlier inference run wrote, one with source: rosetta_stone. For a
wrong mapping from any other source, still propose the change with its
evidence: the workflow declines it and shows it to a person.
Replace or remove only on evidence you can point to in the sample, the statistics or the attribute's definition. A mapping someone else wrote that you would have written differently, but that isn't wrong, is kept.
3. Map the columns
Apply sections 1-4 of the rules to every column, using the evidence from
step 1. A column an existing mapping reads can hold more attributes than
the one it's mapped to (the rules' "Map every attribute the column
holds"): look for those. The attribute it's already mapped to was settled
in step 2. Run /find-attribute with --no-confirm, validate every
expression with narrative_nql_validate, and score each mapping.
- Propose every candidate you scored, with its confidence, even a low one. Don't hold one back for its score: the workflow decides which proposals are confident enough to apply.
- Don't add an attribute the dataset already maps. If the existing mapping is wrong, replace it (step 2).
- Add each attribute at most once. When two columns could fill the same attribute, pick one, or combine them in one expression.
4. Account for every column
Every column you didn't skip in step 1 is read by an existing mapping
you keep or replace, by a proposed add, or listed in unmapped with
one of these reasons:
reason |
When |
|---|---|
noFittingAttribute |
No Rosetta Stone attribute fits the values. |
coveredByRule |
A derivation rule already fills the attribute from another mapping on the dataset. |
noValues |
The column is empty in both the sample and the statistics. |
invalidExpression |
No expression for the best candidate validated. Name the candidate and what failed in detail. |
Put anything that helps a reader in detail, in one sentence.
5. Answer
Answer with the structured output only: no summary, no questions, no text around it. The run's answer schema is the contract; this is its shape:
{
"schemaVersion": 1,
"proposals": [
{
"action": "add",
"attributeId": 118,
"mapping": { "type": "value_mapping", "expression": "TRIM(email)" },
"confidence": 95,
"reasoning": "Every sampled value is an email address."
},
{
"action": "replace",
"mappingId": "6f1c…",
"attributeId": 46,
"mapping": { "type": "value_mapping", "expression": "UPPER(TRIM(state))" },
"confidence": 90,
"reasoning": "USPS abbreviations, upper case.",
"evidence": "The existing mapping keeps lower-case values, which the attribute's enum doesn't accept."
},
{
"action": "remove",
"mappingId": "0b2e…",
"confidence": 85,
"reasoning": "A derivation rule gives the dataset this attribute.",
"evidence": "raw_email is mapped from email, and normalized_email derives from it."
}
],
"kept": [
{ "mappingId": "9a41…", "confidence": 92 }
],
"unmapped": [
{ "column": "fnlwgt", "reason": "noFittingAttribute", "detail": "A census sampling weight." }
]
}
mappingis the body the mappings API takes:value_mappingwith anexpression, orobject_mappingwithproperty_mappingsofpathandexpression. Leave the per-property confidence and reasoning out; the proposal'sconfidenceis the lowest of them.addcarriesattributeIdandmapping, andmappingIdwhen it takes the place of an existing mapping youremove.replacecarriesmappingId,attributeId,mappingandevidence.removecarriesmappingIdandevidence.- Keep
reasoning,evidenceanddetailto a sentence or two. Name attributes by name in them, not only by id. proposals,keptandunmappedare always present, even when empty.
Edge cases and gotchas
- A tool call is refused. Don't retry it and don't look for another way to make the change. Put the change in your answer.
- The dataset is wide. Describe it once, then read statistics for
the columns you are mapping with
narrative_dataset_get_column_statsrather than describing again. - Nothing is mappable. Answer with empty
proposals, the existing mappings underkept, and every column underunmapped. - An expression won't validate. Fix it with the rules' references
and validate again. If it still fails, don't propose it; list the
column as
invalidExpressionand say what failed indetail.
Harness fallbacks
narrative-mcpis unavailable. You can't read the dataset or validate anything. Answer with emptyproposals,keptandunmapped.narrative-knowledge-baseis unavailable. The rules skill recommends it for hard cases; continue with the rules' local references.