narrative-io/narrative-skills-marketplace / plugins/narrative-common/skills/rosetta-stone-mapping-rules
rosetta-stone-mapping-rules
VerifiedThe 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)
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.3 KB |
| SKILL.md.tmpl | other | 19.8 KB |
| references/EDGE_CASES.md | markdown | 2.3 KB |
| references/ENUM_HANDLING.md | markdown | 5.3 KB |
| references/EXPRESSION_SYNTAX.md | markdown | 8.7 KB |
| references/KB_RESEARCH.md | markdown | 6.9 KB |
references/EDGE_CASES.md
View on GitHub# Edge cases and gotchas
Read when an expression won't validate, an enum-constrained
attribute is involved, you're being asked to fix one property of
an object_mapping, the dataset has columns that don't fit Rosetta
Stone, or a mapping is failing for a reason the body procedure
doesn't address.
## Reserved SQL identifiers MUST be double-quoted
`type`, `value`, `user`, `order`, `group`, `select` are reserved.
Write `column."type"`, never `column.type`. See
`EXPRESSION_SYNTAX.md`.
## Enum constraints are case-sensitive
`'SHA256'` does NOT match `'sha256_email'`. When source values
don't match the enum, generate a `CASE WHEN` and lower confidence.
See `ENUM_HANDLING.md`.
## Null handling is automatic at runtime
Do NOT add `COALESCE` to mask nulls and do NOT flag null inputs as
edge cases. Nulls in test results from null inputs are expected.
## Object-mapping property_mappings is replace-all
When suggesting a fix to one property of an object mapping, include
*every* existing property_mapping in the suggested mapping — the
API replaces the whole array.
## Custom attributes are a fallback, not a primary path
Only mention them in the summary when (a) zero Rosetta Stone
matches exist for the dataset, or (b) several columns are clearly
proprietary (internal_id, custom_metric_x, etc.).
## Don't paraphrase the attribute catalog
If you'd benefit from the attribute description, just call
`narrative_attributes_describe` — don't reason from the search
snippet alone.
## Mapping confidence ≠ NQL validity
A 100% valid NQL expression can still be a low-confidence mapping
(e.g., `name` column → first name attribute vs full name attribute).
Validate syntactically, then score semantically.
## Token economy
Prefer the existing sample returned by
`narrative_datasets_describe(include: ["sample"])` over enqueuing a
fresh `narrative_dataset_request_sample` job. The existing sample
is almost always enough to spot the patterns this skill needs, and
re-sampling costs a job round-trip.
## Skip underscore-prefixed columns
Columns starting with `_` (e.g., `_nio_last_modified_at`,
`_nio_sample_128`) are reserved platform-managed columns. The
platform auto-generates mappings for them when needed (tagged
`nio_system` / `nio_dataset_implicit_attribute` in `mappings[]`).
Don't propose mappings for them and don't list them as unmapped in
warnings.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |