mapping-builder
/mapping-builder
Build a reviewed crosswalk (RequirementMappingSet YAML library + review xlsx/csv) between two CISO Assistant framework YAML files using Claude itself as the reasoning engine. Zero infrastructure — stdlib + pyyaml only, no embedders, no LM Studio, no Qdrant. Use when the user asks to map / crosswalk / generate a mapping between two frameworks (e.g. ccb-cff-2023-03-01.yaml ↔ cyfun2025.yaml), wants to contribute a community mapping to backend/library/libraries/, or says things like "build a mapping between framework X and Y", "create a crosswalk YAML", "generate requirement_mapping_set". Output m
- Author
- intuitem ↗
- Repository
- ciso-assistant-community ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 8
- Scripts
- 7
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 7 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/audit_verdicts.py, scripts/cat_slice.py, scripts/diff_mappings.py, scripts/parse_framework.py, scripts/render_html.py, scripts/write_mapping_yaml.py, scripts/write_review.py
What it does and when to use it
Build a reviewed crosswalk (RequirementMappingSet YAML library + review xlsx/csv) between two CISO Assistant framework YAML files using Claude itself as the reasoning engine. Zero infrastructure — stdlib + pyyaml only, no embedders, no LM Studio, no Qdrant. Use when the user asks to map / crosswalk / generate a mapping between two frameworks (e.g. ccb-cff-2023-03-01.yaml ↔ cyfun2025.yaml), wants to contribute a community mapping to backend/library/libraries/, or says things like "build a mapping between framework X and Y", "create a crosswalk YAML", "generate requirement_mapping_set". Output m
Triggers from the description
Original author description
Build a reviewed crosswalk (RequirementMappingSet YAML library + review xlsx/csv) between two CISO Assistant framework YAML files using Claude itself as the reasoning engine. Zero infrastructure — stdlib + pyyaml only, no embedders, no LM Studio, no Qdrant. Use when the user asks to map / crosswalk / generate a mapping between two frameworks (e.g. ccb-cff-2023-03-01.yaml ↔ cyfun2025.yaml), wants to contribute a community mapping to backend/library/libraries/, or says things like "build a mapping between framework X and Y", "create a crosswalk YAML", "generate requirement_mapping_set". Output m
How it works
- What this skill does
- How to use the helpers
- Workflow
- Output schema reference
- Common mistakes to avoid
- Quick reference
SKILL.md preview
---
name: mapping-builder
description: Build a reviewed crosswalk (RequirementMappingSet YAML library + review xlsx/csv) between two CISO Assistant framework YAML files using Claude itself as the reasoning engine. Zero infrastructure — stdlib + pyyaml only, no embedders, no LM Studio, no Qdrant. Use when the user asks to map / crosswalk / generate a mapping between two frameworks (e.g. ccb-cff-2023-03-01.yaml ↔ cyfun2025.yaml), wants to contribute a community mapping to backend/library/libraries/, or says things like "build a mapping between framework X and Y", "create a crosswalk YAML", "generate requirement_mapping_set". Output matches the schema in backend/library/libraries/mapping-*.yaml exactly so the result is PR-able.
---
# Mapping Builder
## What this skill does
Generate a CISO Assistant `requirement_mapping_set` library YAML — plus a human-review xlsx/csv — by reasoning over two framework YAMLs entirely in this conversation. No embedders, no local LLMs, no vector DBs.
The output YAML drops directly into `backend/library/libraries/` and is loadable by the platform's library loader.
**When NOT to use this skill:**
- For mapping huge frameworks (>500 assessable items per side). The conversation context fills up. Use `tools/mapping_builder/map_v2.py` instead — it has hybrid retrieval and runs locally.
- For batch/automated runs that need to be deterministic across sessions. Use the local CLI.
## How to use the helpers
Stdlib + pyyaml scripts under `.claude/skills/mapping-builder/scripts/`. All invocations in this doc assume you run from the repo root with the project's venv.
```bash
SKILL=.claude/skills/mapping-builder/scripts # shorthand for the examples below
# Parse a framework YAML → JSON with assessable items grouped by section.
# Emits warnings on stderr: empty-description items, too-few-sections hint.
.venv/bin/python $SKILL/parse_framework.py path/to/framework.yaml > parsed.json
# Slice items by Category (e.g. ID.AM, PR.AC) rather than top-level Function.
# Use this when parse_framework warns that sections are too coarse.
.venv/bin/python $SKILL/cat_slice.py parsed.json # summary mode
.venv/bin/python $SKILL/cat_slice.py parsed.json ID.AM,GV.OC # filter mode
# Emit the mapping library YAML from a verdicts spec.
.venv/bin/python $SKILL/write_mapping_yaml.py spec.json output.yaml
# Emit a review xlsx (or csv if openpyxl missing).
.venv/bin/python $SKILL/write_review.py spec.json source_parsed.json target_parsed.json review.xlsx
# Audit the running verdicts jsonl: coverage, unmapped items, low-strength verdicts.
.venv/bin/python $SKILL/audit_verdicts.py parsed_src.json verdicts.jsonl --threshold 6
# Diff two mapping YAMLs (or a YAML vs jsonl) — great for eval against a published mapping.
.venv/bin/python $SKILL/diff_mappings.py A.yaml B.yaml --sample 5
# Render a standalone interactive HTML (category heatmap + filterable pair list).
.venv/bin/python $SKILL/render_html.py spec.json src_parsed.json tgt_parsed.json out.html
```
The `spec.json` for `write_mapping_yaml.py` and `write_review.py` is built up across the workflow below — see the docstrings of the scripts for the exact field shape.
## Workflow
Run the steps in order. Do NOT skip the section-affinity step — it is the single most important quality lever and prevents wasting context on irrelevant pairs.
### Step 1 — confirm the request and check for duplicates
Before doing any work, confirm with the user:
- Source framework YAML path
- Target framework YAML path
- Direction matters: source maps INTO target
Then `Glob` for `backend/library/libraries/mapping-*.yaml` and check if a published mapping for this exact pair already exists. If yes, surface it to the user — they may want to extend rather than recreate.
### Step 2 — parse both frameworks
```bash
.venv/bin/python .claude/skills/mapping-builder/scripts/parse_framework.py \
backend/library/libraries/SOURCE.yaml > /tmp/src.json
.venv/bin/python .claude/skills/mapping-builder/scripts/parse_framework.py \
backend/library/libraries/TARGET.yaml > /tmp/tgt.json
```
`Read` both JSONs (or summarize via the CLI if too large) and confirm the framework sizes with the user. Note `n_assessable` and `n_sections` for each side.
**Hard limit check**: if either side has > 500 assessable items, stop and recommend the local CLI (`tools/mapping_builder/map_v2.py`). Don't try to power through — context will fail mid-mapping.
**Check for parse warnings**: `parse_framework.py` writes warnings to stderr (and a `warnings` array in the JSON). Two kinds you'll see:
- **Empty-description items** — assessable items in the source YAML with no name and no description. They can't be mapped; surface them to the user as known gaps.
- **Too-few-sections hint** — fires when there are ≤8 top-level sections but many items (NIST CSF-style frameworks: 5 Functions in v1.1, 6 in v2.0). In this case the `sections` list is useless for affinity — use Category-level slicing via `cat_slice.py` instead (see Step 3).
### Step 3 — section-affinity narrowing (DO NOT SKIP)
Read the `sections` array from each parsed JSON (typically 5-30 entries per side, so cheap to consider in full).
**If parse warned about coarse sections**, use `cat_slice.py` to list categories on both sides instead:
```bash
.venv/bin/python .claude/skills/mapping-builder/scripts/cat_slice.py /tmp/src.json # summary → stderr
.venv/bin/python .claude/skills/mapping-builder/scripts/cat_slice.py /tmp/tgt.json
```
Then build affinity at the Category level (e.g. `ID.AM → ID.AM + GV.OC + GV.RR`) rather than at the Function level. NIST CSF 2.0 restructuring moves many CSF 1.1 Categories across Functions (e.g. `ID.GV → GV.PO/GV.RR`, `PR.IP → PR.PS/PR.IR/ID.IM`), so affinity must operate at that granularity.
Build a section affinity table by reasoning over section names alone — for each source section, identify the 1-3 target sections most likely to contain real mappings:
```text
SOURCE section ID.AM (Asset Management)
→ likely targets: ID.AM (direct), GV.OC (governance overlap)
SOURCE section PR.AC (Access Control)
→ likely targets: PR.AA (Access Authentication)
... etc
```
Print this affinity table to the user, ask them to sanity-check it. If they correct anything, update before proceeding. **This is where most recall is won or lost** — embedders systematically over-match on shared jargon; reading section names is more discriminating.
### Step 4 — per-section deep dive
For each `(source_section, [target_sections])` entry from Step 3, do the following in order:
1. Pull the source items that belong to `source_section` and the target items that belong to any of the `target_sections`. With section narrowing, this is typically 5-20 sources × 5-30 targets = 25-600 candidate pairs per section.
2. Read each source item's `full_sentence`, then read all candidate targets' `full_sentence`.
3. For each source, decide which targets are real mappings. Output a JSON list of verdicts:
**Affinity is a starting heuristic, not a fence.** Expect to expand target categories mid-section as you encounter obvious cross-matches — e.g. while mapping `ID.AM` in CCB CFF you'll find `ID.AM-6.1` (roles/responsibilities) clearly belongs with `GV.RR` in CSF 2.0, even if you didn't list `GV.RR` as a Step-3 target for `ID.AM`. When this happens, pull the extra target category via `cat_slice.py` and continue. Don't force a bad match just because affinity said only one target. Mention the expansion to the user so they can sanity-check.
```json
{
"source_requirement_urn": "...",
"target_requirement_urn": "...",
"relationship": "equal | intersect | subset | superset",
"strength_of_relationship": 0-10,
"rationale": "one-sentence why"
}
```
Relationship rubric (matches the platform enum):
- **equal**: same obligation, interchangeable for audit. Reverse maps to equal.
- **intersect**: meaningful overlap, neither covers the other. Reverse maps to intersect.
- **subset**: source is contained within target's scope. Reverse maps to superset.
- **superset**: source is broader than target. Reverse maps to subset.
- (`not_related` is never emitted — just omit the pair from the verdicts.)
`strength_of_relationship` is a 0-10 confidence in the *existence* of the mapping (NOT in the equal/intersect label).
Append verdicts to a running `verdicts` list. Persist the running list to `/tmp/<mapping_name>_verdicts.jsonl` after each section so progress is recoverable.
### Step 5 — borderline review with the user
Before emitting the YAML, run the audit script on the running verdicts jsonl:
```bash
.venv/bin/python .claude/skills/mapping-builder/scripts/audit_verdicts.py /tmp/src.json /tmp/<name>_verdicts.jsonl --threshold 6
```
It reports coverage %, unmapped source items (split into empty-description YAML bugs vs. real gaps), relationship/strength distributions, and every verdict ≤ threshold.
Surface ambiguous calls to the user. Specifically:
- All verdicts with `strength_of_relationship` ≤ 6 (listed by the audit)
- Pairs where the equal vs intersect call could go either way
- Source items that ended up with zero verdicts (might indicate a missed section pairing) — the audit separates these from YAML-bug unmapped items
Show source/target text side-by-side and your rationale. Let the user override `relationship`, override `strength_of_relationship`, or drop the pair entirely. Apply edits to the running verdicts list.
### Step 6 — emit YAML + review file
Build the `spec.json`:
```python
{
"ref_id": f"mapping-{source_ref_id_lower}-and-{target_ref_id_lower}",
"name": f"{source_framework_name} <-> {target_framework_name}",
"description": "...",
"version": 1,
"publication_date": today_iso,
"copyright": "...", # ask the user
"provider": "...", # ask the user
"packager": "...", # ask the user
"source_library_urn": <from src.json[\"library_urn\"]>,
"source_framework_urn": <from src.json[\"framework_urn\"]>,
"target_library_urn": <from tgt.json[\"library_urn\"]>,
"target_framework_urn": <from tgt.json[\"framework_urn\"]>,
"verdicts": [...]
}
```
Pull the URNs straight from the parsed JSON — do NOT construct them by hand. The library URN slug is not always the same as the framework `ref_id` (e.g. `cyfun2025` → `urn:intuitem:risk:library:ccb-cyfun2025`).
Then run:
```bash
.venv/bin/python .claude/skills/mapping-builder/scripts/write_mapping_yaml.py \
/tmp/spec.json \
backend/library/libraries/mapping-<source>-and-<target>.yaml
.venv/bin/python .claude/skills/mapping-builder/scripts/write_review.py \
/tmp/spec.json /tmp/src.json /tmp/tgt.json \
/tmp/mapping-<source>-and-<target>_review.xlsx
.venv/bin/python .claude/skills/mapping-builder/scripts/render_html.py \
/tmp/spec.json /tmp/src.json /tmp/tgt.json \
/tmp/mapping-<source>-and-<target>_preview.html
```
The mapping YAML automatically contains both the forward AND reverse mapping sets (subset/superset are auto-flipped on the reverse).
The HTML preview is self-contained (embedded JSON, vanilla JS, no network) — open it in a browser to inspect the mapping. It shows a Category-level heatmap at the top (source categories × target categories with per-cell counts, click to filter) and a filterable pair list below. Categories are bucketed via the same regex as `cat_slice.py` (NIST CSF, ISO Annex A, numeric prefix), with section names shown on hover.
### Step 7 — final summary, no auto-PR
Report to the user:
- Total mappings produced (forward; the reverse is auto-derived)
- Distribution by relationship type
- Path to the YAML library file
- Path to the review xlsx
- Path to the HTML preview
- Suggested commit message
**If a prior published mapping existed** (flagged in Step 1), run `diff_mappings.py` against it and report the shared/only-in-A/only-in-B breakdown plus label disagreements. This is the most useful evaluation signal: pairs only in the published version may point to secondary intersects the rebuild missed; pairs only in the rebuild may point to real gains worth retaining.
Do NOT auto-commit or auto-push. The user is putting their name on a community contribution; they confirm before pushing. If they ask, then `git checkout -b <branch>` and stage the new YAML.
## Output schema reference
The emitted YAML must match this top-level shape exactly (the `write_mapping_yaml.py` script enforces it):
```yaml
urn: urn:intuitem:risk:library:<ref_id>
locale: en
ref_id: <ref_id>
name: <name>
description: <description>
copyright: ...
version: 1
publication_date: YYYY-MM-DD
provider: ...
packager: ...
dependencies:
- <source library URN>
- <target library URN>
objects:
requirement_mapping_sets:
- urn: urn:intuitem:risk:req_mapping_set:<ref_id>
ref_id: <ref_id>
name: <name>
description: ...
source_framework_urn: <source framework URN>
target_framework_urn: <target framework URN>
requirement_mappings:
- source_requirement_urn: ...
target_requirement_urn: ...
relationship: equal | intersect | subset | superset
strength_of_relationship: 0-10 # optional
rationale: semantic # enum: syntactic | semantic | functional (CharField max 20)
annotation: ... # the verdict's free-text "rationale" lands here
- # reverse mapping set, auto-derived
...
```
Look at any existing `backend/library/libraries/mapping-*.yaml` for a real example.
## Common mistakes to avoid
- **Skipping section affinity** and trying to consider source × target pairs blindly — context fills up and recall drops.
- **Constructing URNs by string concatenation** instead of pulling them from the parsed framework JSONs. Library and framework URN slugs are not always equal to ref_id.
- **Only emitting the forward mapping set.** The platform expects two sets in the library (forward + reverse). The `write_mapping_yaml.py` script generates the reverse automatically — don't bypass it.
- **Forgetting `subset` ↔ `superset` flip on reverse.** The script handles this; if you write the YAML by hand, you'll get it wrong.
- **Auto-committing the result.** This is a community contribution; the user always confirms.
- **Using `not_related` as a relationship value.** It's not in the published schema. Just omit pairs that aren't real mappings.
## Quick reference
| File | Purpose |
|---|---|
| `scripts/parse_framework.py` | Framework YAML → JSON with items grouped by section; emits warnings for empty-description items and coarse-section frameworks |
| `scripts/cat_slice.py` | Slice parsed items by Category (e.g. `ID.AM`, `PR.AC`); summary mode or filter mode |
| `scripts/write_mapping_yaml.py` | Verdicts spec → published-format library YAML (forward + reverse) |
| `scripts/write_review.py` | Verdicts spec + parsed frameworks → xlsx (or csv fallback) for human audit |
| `scripts/audit_verdicts.py` | Verdicts jsonl (or mapping YAML) + parsed source → coverage %, unmapped items, low-strength verdicts |
| `scripts/diff_mappings.py` | Compare two mapping YAMLs (or YAML vs jsonl) — shared / only-A / only-B / label disagreements |
| `scripts/render_html.py` | Standalone HTML preview: category heatmap + filterable pair list (no network deps) |
Files in this package (8)
- SKILL.md 15 KB
- scripts/audit_verdicts.py 6 KB
- scripts/cat_slice.py 4 KB
- scripts/diff_mappings.py 5 KB
- scripts/parse_framework.py 6 KB
- scripts/render_html.py 25 KB
- scripts/write_mapping_yaml.py 8 KB
- scripts/write_review.py 5 KB
Versions
The database has no other skills named mapping-builder.
Database snapshot: 13.11.2026 · package version 1ec59e3ae976 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100reference-controls-enricher
Enrich a CISO Assistant framework YAML by linking each assessable requirement to reference control URNs from the central doc-pol library (CISO Assistant Key Reference Controls). Produces a reviewable xlsx and patches the framework YAML in place. Use when the user asks to "add… - 90grc-framework-crosswalk-diagram
Use when creating a draw.io diagram for mapping controls and obligations across frameworks to show overlap, gaps, and conflicts in a GRC, security, audit, compliance, privacy, cloud, or risk context. - 100np-bank-regulatory-crosswalk
Build a bank regulatory evidence crosswalk. Use when a bank needs to map an actual obligation to implementation evidence. - 100cis-benchmark-framework
Convert a CIS Benchmark PDF into a CISO Assistant framework library (YAML) by extracting only the "Appendix: Summary Table" — recommendation numbers, titles, and their Automated/Manual tag as implementation groups. Stays within the same IP boundary as the existing… - 100token-crosswalk-builder
Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — then wire the tokens:validate CI gate. Use this when retrofitting a design system onto a mature codebase, when the user wants to map…