DenisSergeevitch/ex-ussr-kinship-research

What this project is

ex-USSR Kinship Research is a set of instructions and tools that turns an AI coding agent (like Codex or Claude Code) into a careful family-history researcher for the former Soviet Union, the Soviet Union, and the Russian Empire. It's not a website or a database — it's a "skill" you install into an AI agent's working environment, so the agent can help you trace ancestors using church books, civil records, military files, deportation and repression documents, and unindexed archive scans.

The core idea is evidence-first: the agent keeps every find traceable, clearly separates raw records from its own interpretation, and states plainly what is proven and what is not.

What it covers

All 15 former Soviet republics: Russia, Ukraine, Belarus, Moldova, Estonia, Latvia, Lithuania, Georgia, Armenia, Azerbaijan, Kazakhstan, Kyrgyzstan, Tajikistan, Turkmenistan, and Uzbekistan. The skill's internal instructions are written in Russian, but the agent talks to you in your own language (English, Ukrainian, Russian, Polish, German, etc.), quotes sources in their original spelling with translations, and builds search queries in the languages of the records.

What it actually does

• Case intake and scope — you give one research question, known facts, who may be alive, and what's off-limits.
• Reproducible registers — it keeps structured records of persons, artifacts, claims, relationships, and a full search log (as CSV files), plus a final report template.
• Historical jurisdiction model — every event is resolved to the state, province, district, parish, or civil registry as of the event date, not today's map. This matters because borders and administrative divisions changed constantly in this region.
• Name-variant matrices — handles pre-reform Russian, Ukrainian, Polish, Romanian, German, and Yiddish name forms, patronymics, maiden names, and transliterations, so the same person isn't missed under a different spelling.
• Source strategy — prioritizes originals first, then official catalogs, indexes, published document collections, and only uses family trees and forums as leads.
• Evidence protocol — claims get statuses like hypothesis, single-source, corroborated, strongly-corroborated, contradicted, or unresolved — not percentages. Copies of the same record share an independence_group, so they never count as independent proof.
• Identity resolution — people with the same name stay as separate entries until distinguishing evidence appears (house number, parents, godparents, exact birth date, or military unit).
• Audit script — checks that all references are consistent and flags weak corroboration before you write conclusions. It also verifies the final report: every cited ID must exist in the registers, and every status must match.
• Final report — lays out every relationship edge by edge, with contradictions, failed searches, and concrete next steps.

How to install and use it

You clone the repository into your AI agent's skills folder:

# For Codex
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-research

# For Claude Code (personal skills)
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

Then you just describe your family question in plain language, for example:

• "My great-grandfather was exiled to Kazakhstan in the 1930s. Help me find his parents in church records."
• "Here are scans of a marriage certificate and a soldier card. Check whether they are the same person and build the evidence chain."
• "Find the parish and the right FamilySearch film for a village in Podolia in the 1890s and read the births for the surname X."

There are also command-line scripts you can run from the skill folder:

• init_case.py — starts a new research case (refuses to create one inside the skill folder, even with --force)
• hash_artifact.py — computes a SHA-256 hash for every saved scan or document
• audit_evidence.py — checks the registers before writing the final report
• build_pdf.py — converts an HTML report to PDF (requires Chrome, Chromium, or Edge installed)

Only Python 3 and the standard library are needed for the scripts; build_pdf.py additionally needs a Chromium-based browser. Private case data should be kept outside the skill's Git checkout.

Repository layout

The project is organized as:

• SKILL.md — main instructions (workflow, hard rules, language policy)
• references/ — detailed guides: source strategy, evidence protocol, locale guide (jurisdictions, name variants, calendars, record types), browser and CAPTCHA handling, privacy and safety, curated starting sources, field lessons, changelog, photo search, and a Habsburg Galicia/Bukovina guide
• assets/ — case intake templates, CSV register templates, final report template, photos README template, and a readable PDF template
• scripts/ — the four Python scripts mentioned above
• evals/ — trigger and reasoning test cases
• tests/ — unit tests

Responsible use rules

The skill has explicit guardrails:

• Family history, not surveillance — it refuses to look up current addresses, phones, or accounts of living people, and minimizes their data in reports.
• No bypassing — no CAPTCHA solving, no paywall/geo-block/rate-limit evasion, no leaked databases. Sign-ins are done by the user.
• No uploads of your documents or DNA data to third-party services without your explicit consent.
• Sensitive findings (deportation, repression, adoption, DNA surprises) are reported neutrally and only as far as the question requires.
• Archive access rules change — the skill only drafts archive requests; it never sends them, and you should always check current official procedures.

Contributing and license

New sources are welcome in references/seed-sources.md — with verified owner, jurisdiction, collection, provenance, IDs, access, restrictions, and check date where known; gaps should be marked rather than guessed. Personal data must be kept out of examples.

The project is MIT-licensed, © 2026 Denis Shiryaev, and maintained by Denis Shiryaev (@DenisSergeevitch).

In short

If you have ancestors from the former USSR and want to research them with an AI agent, this skill gives that agent a disciplined, evidence-based workflow: it knows the historical jurisdictions, handles name variations across languages, keeps rigorous track of what's proven and what isn't, and produces a verifiable final report — all while respecting privacy and access rules.