Name Framework Migration Third Step
Developmentname-framework-migration-third-stepName Framework Migration Third 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.
Complete the name framework migration in a crawler (Step 3) by removing all custom name cleaning/splitting logic and the Step 1 review scaffolding, replacing it with a single h.apply_reviewed_name_string or h.apply_reviewed_names call. Use only after Step 1 has been deployed and run in production and the dataset's name reviews have been completed (Step 2).
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-third-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-third-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 3 of the name framework migration in $ARGUMENTS.
zavod/docs/extract/names.md#migrating-to-the-name-cleaning-helpers (the "Step 3" subsections) is the authoritative procedure and holds the exact code — follow it, do not rely on a paraphrase here. This skill only orients you and covers the mechanics of running it.
Preconditions
Do not run Step 3 until Step 1 has been deployed and run in production (the crawler already calls h.review_names) and Step 2 is done (the dataset's name reviews are completed). Step 3 hands cleaning to the review system, and unaccepted reviews fall back to the raw string — so incomplete reviews change the output. If you cannot confirm both, stop and tell the user.
Branch setup
Derive a branch name from the crawler path: take the dataset name (the directory containing crawler.py) and prefix it with name-migration-step3/ (e.g. datasets/us/ga/med_exclusions/crawler.py → name-migration-step3/us-ga-med-exclusions). Then git checkout -b <branch-name> and confirm you are on it before proceeding.
Crawler source
!cat $ARGUMENTS
Read first
zavod/docs/extract/names.md#migrating-to-the-name-cleaning-helpers— the "Step 3" subsections are authoritative for the exact codezavod/zavod/helpers/names.py— signatures forapply_reviewed_name_string,apply_reviewed_names,Names
What Step 3 changes
- Remove all custom splitting/cleaning and the Step 1 scaffolding it was added alongside:
original,suggested,h.check_names_regularity,h.review_names, and the manualentity.add("name"/"alias", ...)calls that drove output. - Keep the raw source string capture (the
.pop(...)) and the entity id. - Follow the doc for the replacement call: sanctions/debarment →
apply_reviewed_name_stringwith nollm_cleaning; non-sanctions → the same withllm_cleaning=True; multiple source name fields →apply_reviewed_nameswith anh.Names(...). string=(or theNamesvalues) must be the unmodified raw source string; preserve anylang=the removedentity.addused; call the helper at most once per entity.
After the edit, tell the user to check, once the Step 3 deployment has run, that new names were not auto-accepted between deploying Step 1 and Step 3.
After changes
After every edit, run uvx ruff check --fix $ARGUMENTS && uvx ruff format $ARGUMENTS and fix anything it reports.
Once ruff passes, git add $ARGUMENTS and output this suggested commit message (do not commit):
[<dataset_slug>] name migration step 3
where <dataset_slug> strips datasets/ and /crawler.py and replaces / with _ (e.g. datasets/us/ga/med_exclusions/crawler.py → [us_ga_med_exclusions] name migration step 3).
Do not
- Do not run Step 3 before its preconditions hold (Step 1 deployed and run, Step 2 reviews completed)
- Do not enable
llm_cleaningfor sanctions datasets - Do not pass a cleaned/split/modified string to
string= - Do not leave any custom cleaning or Step 1 scaffolding behind
- Do not guess
Namesfield names or helper signatures — readzavod/zavod/helpers/names.py