Name Framework Migration First Step
Developmentname-framework-migration-first-stepName Framework Migration First Step is an Agent Skill for development published in the opensanctions/opensanctions repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Migrate ad-hoc name cleaning in a crawler to h.review_names (Step 1 of the name framework migration). Use when a crawler.py contains delimiter splits, regex substitutions, bracket stripping, or conditional logic applied to name strings before the name is added or applied.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/opensanctions/opensanctions/blob/HEAD/.claude/skills/name-framework-migration-first-step/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/name-framework-migration-first-step, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Perform Step 1 of the name framework migration in $ARGUMENTS: introduce h.review_names alongside the existing cleaning logic.
Branch setup
Before making any changes:
- Derive a branch name from the crawler path by taking the dataset name (the directory containing
crawler.py) and prefixing it withname-migration/. For example,datasets/us/ga/med_exclusions/crawler.py→name-migration/us-ga-med-exclusions. - Create and check out the branch:
git checkout -b <branch-name> - Confirm you are on the new branch before proceeding.
Crawler source
!cat $ARGUMENTS
Read first (in order)
- examples/migrations.md — real before/after migrations; read before touching any crawler
zavod/docs/extract/names.md#migrating-to-the-name-cleaning-helpers— full three-step procedure and rationalezavod/zavod/helpers/names.py— exact signatures forreview_names,check_names_regularity,Names
Trigger patterns to find
Scan the crawler for any of these before acting:
# Delimiter splits
last_name, name = name_raw.split(",", 1)
name, *aliases = h.multi_split(raw, SPLITS)
# Bracket/parenthesis stripping
name = name.replace("(Acting)", "")
name = name.strip("„")
# Regex substitutions or splits on name content
parts = re.split(r"(?i)\baka\b", name, maxsplit=1)
names = h.multi_split(name_raw, ["(w zapisie także", "(", ")"])
# Conditional checks on name content before apply_name
if len(name_split) > 1:
entity.add("alias", name_split[1:])
Migration steps
zavod/docs/extract/names.md (the "Step 1" subsections) is the authoritative procedure and holds the exact code for each path — follow it, do not rely on a paraphrase here. This section only orients you and flags what's specific to running it as a skill.
First decide the path by dataset type:
- Sanctions / debarment dataset (e.g. tagged
list.sanctionorlist.debarment): mirror the existing cleaned names into asuggested = h.Names(), then callh.check_names_regularityandh.review_names(..., suggested=..., is_irregular=..., default_accepted=True). - Non-sanctions dataset: leave the existing logic untouched and add
h.review_names(context, entity, original=original, llm_cleaning=True)— nosuggested, nois_irregular. Then reconcile any custom alias-marker list (e.g. aNAME_SPLITSconstant) againstrigour.names.name_split_phrases_list()and add uncovered phrases asreject_stringsundernames.schema_rules, per the doc.
Invariants for both paths:
originalis the unmodified raw source string, captured before any cleaning.- Existing
entity.add/h.apply_namecalls stay in place unchanged and keep driving output; reviews are not applied until Step 3. - Call
h.review_namesat most once per entity.
Tell the user, after the edit: for sanctions, check a sample of created reviews and confirm the export has no name changes, and deploy Step 3 ASAP so new entities aren't default-accepted; for non-sanctions, check a sample of the LLM extraction.
After changes
After every edit to the crawler file, run:
uvx ruff check --fix $ARGUMENTS && uvx ruff format $ARGUMENTS
Fix any errors ruff reports before proceeding.
Once all changes are complete and ruff passes, stage the file:
git add $ARGUMENTS
Then output the suggested commit message (do not commit):
[<dataset_slug>] name migration
where <dataset_slug> is derived from the path by stripping datasets/ and /crawler.py and replacing / with _ (e.g. datasets/us/ga/med_exclusions/crawler.py → [us_ga_med_exclusions] name migration).
Do not
- Do not proceed to Step 3 of the three-step migration procedure (switching to
apply_reviewed_names) — that requires completed reviews first - Do not construct
Namesby guessing field names — readzavod/zavod/helpers/names.pyfirst - Do not add explanatory comments beyond what the code requires