name: ex-ussr-kinship-research description: Исследует родственные связи и семейную историю по персональным данным и документам с фокусом на бывший СССР, СССР и Российскую империю. Использовать для генеалогического поиска, сопоставления однофамильцев, архивных, метрических, военных, миграционных и репрессивных записей, построения доказательной цепочки и итогового отчёта. Не использовать для слежки за живыми людьми, поиска их текущих контактов или адресов, доступа к закрытым данным, обхода защиты и утверждения биологического родства без независимого подтверждения. EN — evidence-first genealogy and family-history research for the former USSR, the USSR and the Russian Empire (church/metric books, civil registration, military, migration, deportation and repression records, unindexed archive scans, namesake disambiguation, evidence chains, final report). Replies in the user's language. Not for tracking living people. compatibility: Предпочтительны внутренний браузер или веб-поиск, чтение PDF/DOCX/изображений и создание файлов. Без браузера skill анализирует материалы пользователя, ведёт реестры и формирует воспроизводимый план поиска, но не заявляет, что веб-поиск выполнен. Работает как skill для Codex и Claude Code. metadata: version: "1.1.0" language: "ru" reply_language: "user" region: "ex-USSR"

Назначение

Установить или опровергнуть родственные связи через воспроизводимое исследование. Сохранять происхождение каждого артефакта, отделять запись от её интерпретации, учитывать исторические границы и варианты имён, а выводы ранжировать по силе доказательств.

Язык общения / Language

Always reply in the user's language. This file is written in Russian, but that does not mean replies should be in Russian.

1. Общаться с пользователем на языке его последнего сообщения: английском, украинском, русском, польском, немецком и т. д. Если пользователь прямо просит другой язык — использовать его.
2. Цитаты из источников приводить в оригинальном написании (кириллица, латиница, старая орфография). Рядом давать перевод на язык пользователя, если он нужен для понимания.
3. Шаблоны из assets/ (отчёт, реестры) заполнять на языке пользователя: заголовки и пояснения переводить. Имена столбцов CSV, идентификаторы (person_id, claim_id, artifact_id) и статусы (single-source, corroborated и т. д.) не переводить.
4. Поисковые запросы составлять на языке источника (русском, украинском, польском, румынском, немецком, идиш и т. д.), а не на языке общения.
5. Язык общения фиксировать в case-intake.yaml в поле requested_output_language. По умолчанию auto — язык пользователя.

Неподлежащие нарушению правила

1. Считать любой новый материал артефактом, а не фактом. Не переносить утверждение из артефакта в вывод без оценки происхождения, читаемости, прямоты и независимости.
2. Не считать копии, зеркала, индексы и пересказы одной записи независимыми подтверждениями. Назначать им общий independence_group.
3. Не присваивать связи статус corroborated без как минимум двух независимых доказательных цепочек. Даже сильный первичный документ до кроссподтверждения помечать single-source.
4. Не сливать двух одноимённых людей только по ФИО, возрасту или населённому пункту. До разрешения личности вести отдельные person_id.
5. Сохранять исходное написание имён, дат и мест. Нормализованные варианты хранить отдельно и явно помечать как исследовательскую форму.
6. Не скрывать противоречия. Фиксировать их рядом с выводом и сохранять альтернативные гипотезы.
7. Для живых людей минимизировать данные. Не искать и не публиковать текущие адреса, телефоны, личные аккаунты, документы-идентификаторы, сведения о несовершеннолетних или иные данные, не необходимые для семейно-исторической задачи.
8. Не загружать пользовательские документы, ДНК-данные или фотографии в сторонние сервисы без явного разрешения пользователя.
9. Не обходить авторизацию, платный доступ, геоблокировку, rate limit, robots/условия сервиса или CAPTCHA. CAPTCHA за пользователя не проходить: остановиться, записать блокировку и передать этот шаг человеку (точный URL и запрос) либо перейти к альтернативному источнику. Запрещены внешние решатели, подмена отпечатка и User-Agent, прокси-ротация, кража cookies и извлечение токенов. Если сайт требует входа, вход выполняет сам пользователь; модель не вводит пароли.
10. Не выдавать отсутствие результата поиска за доказательство отсутствия человека или события.
11. Не выдумывать недостающие сведения и не повышать семейную память до документального факта. Если открытые источники исчерпаны, сказать об этом один раз, подготовить вопросы родственникам и проекты запросов в архивы и остановиться, а не повторять поиски по кругу.

Рабочий процесс

Шаг 1. Зафиксировать задачу и допустимый объём

1. Сформулировать один главный исследовательский вопрос: кто с кем связан, какой тип связи проверяется и за какой период.
2. Зафиксировать известные имена, варианты написания, примерные даты, населённые пункты, конфессию или общину только если это релевантно архивному поиску, занятия, родственников и миграции.
3. Отметить, какие лица могут быть живы. Для них записать заявленную пользователем связь, согласие или иную законную и неинтрузивную основу исследования.
4. Определить запреты пользователя: страны, сервисы, публикация имён, загрузка файлов, платные источники, обращение к архивам.
5. При наличии входных файлов сохранить оригиналы без изменений и работать с копиями.

Использовать структуру assets/case-intake.template.yaml. Подробные ограничения читать в references/privacy-and-safety.md.

Шаг 2. Инициализировать дело и реестры

Создать отдельную директорию дела:

python scripts/init_case.py --case-dir <путь> --research-question "<вопрос>" --subject-label "<основной человек>"

Вести без пропусков:

• case-intake.yaml — задача, рамки, исходные данные и ограничения;
• person-register.csv — отдельные кандидаты на личность;
• artifact-register.csv — каждый документ, веб-результат, изображение или запись;
• claims-register.csv — проверяемые утверждения, извлечённые из артефактов;
• relationship-register.csv — гипотезы о связях между person_id;
• search-log.csv — запросы, фильтры, неудачи, CAPTCHA и следующие шаги;
• final-report.md — итоговое исследование по шаблону.

Для локального файла вычислить контрольную сумму:

python scripts/hash_artifact.py <путь-к-файлу>

Шаг 3. Разобрать материалы пользователя

1. Извлечь текст, таблицы, подписи, штампы, номера актов, архивные шифры и оборотные пометы.
2. Для сканов указать страницу, область и качество чтения. Нечитаемые места обозначать [неразборчиво]; предположения — [предположительно: ...].
3. Не исправлять молча фамилии, даты и географию. Сохранять names_as_written, place_as_written и исходную дату.
4. Для каждого материала создать artifact_id и записать происхождение, дату получения, локальный путь или URL, тип оригинала/копии, читаемость и independence_group.
5. Каждое извлечённое утверждение оформить отдельным claim_id; не объединять несколько логических фактов в одну строку.

Подробную схему оценки читать в references/evidence-protocol.md.

Шаг 4. Построить историко-географическую модель

1. Для каждого события определить юрисдикцию на дату события, а не только современную страну.
2. Развернуть цепочку: страна/империя → губерния/область → уезд/район → волость/сельсовет → приход/ЗАГС → населённый пункт.
3. Составить варианты старых и новых топонимов, языков и письменностей.
4. Записать исходный календарь; не выполнять скрытую конвертацию дат.
5. Построить матрицу вариантов имени: исходное написание, дореформенная форма, местный язык, кириллица/латиница, патроним, фамильное окончание, возможная русификация и бытовые формы.
6. Не считать переводные или созвучные имена эквивалентными без дополнительных признаков.

Читать references/ex-ussr-locale-guide.md только когда появляются исторические границы, смена языка/письменности или неоднозначные топонимы.

Шаг 5. Составить план поиска

1. Начать с наиболее позднего надёжно установленного события и двигаться назад по одной связи за раз.
2. Для каждого пробела определить подходящий тип записи: акт ЗАГС, метрическая книга, исповедная ведомость, ревизская сказка, посемейный/домовой список, перепись, военная запись, эвакуация, репрессия, миграция, адрес-календарь, некролог, кладбищенская запись и т. п.
3. Сначала искать оригинал или официальный каталог; затем индекс; затем вторичные базы и сообщества как источники наводок.
4. Для каждой гипотезы заранее записать, что её подтвердит и что опровергнет.
5. Составить запросы по вариантам имени, месту, диапазону лет, родственникам, профессии, воинской части и архивному шифру.

Подробную тактику и приоритеты источников читать в references/source-strategy.md. Предоставленный пользователем список стартовых ресурсов находится в references/seed-sources.md и не заменяет проверку актуальности и происхождения.

Практические приёмы для неиндексированных сканов (FamilySearch, архивные порталы), документов о репрессиях и депортациях, военных баз, исчезнувших хуторов, оккупированных территорий и ситуации «открытые источники исчерпаны» читать в references/field-lessons.md.

Шаг 6. Выполнить веб-поиск внутренним браузером

Если браузер доступен:

1. Использовать поиск, переходы, фильтры каталогов и просмотр документов последовательно; не отправлять массовые запросы.
2. Для каждого поиска сразу записывать точный запрос, локаль/язык, фильтры, URL, дату доступа и результат в search-log.csv.
3. При обнаружении записи сохранить устойчивый идентификатор, архивный шифр, номер страницы/кадра и прямую ссылку, если она существует.
4. Для сканированных PDF и изображений просматривать саму страницу, а не полагаться только на OCR или сниппет.
5. Не использовать фрагмент поисковой выдачи как конечный источник, если доступна исходная страница.
6. Если браузер недоступен, не имитировать поиск. Подготовить список точных запросов, архивов и ожидаемых типов документов.

CAPTCHA

1. Убедиться, что открывается публично доступный или разрешённый пользователем источник.
2. Не решать CAPTCHA за пользователя: ни встроенным браузером, ни внешними сервисами. Остановиться на этом источнике.
3. Передать шаг человеку: точный URL, поисковый запрос (ФИО, год, регион) и что искать в результате. Пользователь может пройти проверку сам и вернуть найденное.
4. Тем временем искать альтернативный официальный источник: другой портал того же архива, каталог, книгу памяти, публикацию документов.
5. Немедленно остановиться, если требуются чужой аккаунт, телефон, документ, платёж, обход географии, подмена fingerprint, прокси/VPN для уклонения от ограничений или сторонний CAPTCHA-solver.
6. Записать блокировку, тип challenge и альтернативный маршрут в search-log.csv.

Полный протокол читать в references/browser-and-captcha.md.

Шаг 7. Оценить артефакты и извлечь утверждения

Для каждого артефакта отдельно оценить:

• происхождение и архивную ссылку;
• оригинал, изображение оригинала, индекс, копию или пересказ;
• современность событию;
• информанта и его возможную осведомлённость;
• прямое или косвенное отношение к утверждению;
• читаемость и полноту;
• независимость от других артефактов;
• признаки ошибки, позднего исправления или заимствования.

Не использовать числовой «процент истины». Присваивать утверждениям только объяснимые статусы:

• hypothesis — рабочая гипотеза;
• single-source — поддержана одной доказательной цепочкой;
• corroborated — поддержана минимум двумя независимыми цепочками без неразрешённого существенного конфликта;
• strongly-corroborated — несколько независимых цепочек, включая хотя бы одну прямую запись с установленным происхождением;
• contradicted — сильное противоречащее свидетельство;
• unresolved — данных недостаточно или конфликт не разрешён.

Шаг 8. Разрешить личности

1. Сопоставлять не только имя, но и совокупность дат, мест, родственников, профессии, адреса, сословия/статуса, конфессии, свидетелей, воинской части и миграционного маршрута.
2. Вести конкурирующих кандидатов раздельно до появления различающих признаков.
3. Зафиксировать причины каждого слияния или разделения person_id.
4. Проверить круг семьи: супругов, родителей, детей, братьев/сестёр, восприемников, свидетелей и соседей, если это помогает идентификации.
5. Не трактовать проживание в одном хозяйстве как биологическое родство.

Шаг 9. Проверить родственную цепочку

1. Строить сложную связь из отдельных рёбер: например, дед/внук требует двух независимо проверенных связей родитель–ребёнок.
2. Различать биологическую, юридическую, приёмную, опекунскую, сводную и хозяйственную связь.
3. Для каждого ребра перечислить поддерживающие и противоречащие artifact_id/claim_id.
4. Не выводить родство из общей фамилии, ДНК-совпадения без контекста, семейного дерева пользователя или сообщения на форуме.
5. Чувствительные открытия — усыновление, возможное несоответствие отцовства, репрессии, этничность, религия — формулировать нейтрально, только в объёме, необходимом для ответа, и с явной ссылкой на источник.

Шаг 10. Провести аудит доказательств

Запустить:

python scripts/audit_evidence.py --case-dir <путь>

Исправить ошибки ссылочной целостности. Предупреждения о слабом кроссподтверждении не игнорировать и не «закрывать» формальным изменением статуса.

Перед итогом проверить:

1. Каждое существенное утверждение имеет claim_id и ссылки на артефакты.
2. Независимость источников объяснена, а не подсчитана по числу URL.
3. Все существенные противоречия видимы.
4. Отрицательные поиски описывают покрытие, а не доказывают отсутствие.
5. Для живых лиц итог очищен от ненужных персональных данных.
6. В отчёте отделены установленное, вероятное, возможное и неизвестное.

Шаг 11. Подготовить итоговое исследование

Использовать assets/final-report.template.md и заполнить:

1. исследовательский вопрос и объём;
2. краткий вывод с уровнем доказательности;
3. исходные данные и ограничения;
4. методику, локали, варианты имён и поисковые системы;
5. идентифицированных лиц и хронологию;
6. каждую родственную связь как отдельную доказательную цепочку;
7. таблицу артефактов и матрицу утверждений;
8. противоречия и альтернативные гипотезы;
9. неудачные поиски, недоступные источники и CAPTCHA-блокировки;
10. нерешённые вопросы и конкретные следующие шаги;
11. архивные шифры, URL, даты доступа и локальные идентификаторы.

Каждый фактический вывод сопровождать ссылками вида [A-0001; A-0007]. Не утверждать больше, чем показывают эти артефакты.

Обработка ошибок

• Если документ не читается, сохранить его как артефакт, описать дефект и запросить лучшую копию только когда без неё нельзя двигаться дальше.
• Если источник исчез, проверить официальный каталог, веб-архив только в допустимых пределах и зеркала; зеркала не считать независимыми.
• Если архивная юрисдикция неясна, сначала решить топоним и административную принадлежность.
• Если результаты дают несколько однофамильцев, расширить семейный кластер и не выбирать кандидата по интуиции.
• Если источники противоречат друг другу, сохранить обе версии, оценить информанта и искать третий независимый источник.
• Если поиск затрагивает явно живого человека без достаточной семейно-исторической основы, сузить исследование до предоставленных пользователем материалов или прекратить интрузивную часть.
• Если документ и семейная память расходятся (например, место рождения в паспорте и в рассказе), сохранить обе версии как отдельные утверждения со своими источниками. Не подгонять документ под рассказ и не наоборот. Различать «родился» и «вырос».
• Если открытые источники исчерпаны, один раз ясно перечислить установленное, неустановленное и просмотренный объём. Подготовить вопросы живым родственникам и проекты запросов в ЗАГС и архивы (references/field-lessons.md, раздел 8) и остановиться.

ex-USSR Kinship Research

An evidence-first genealogy skill for AI agents (Codex, Claude Code and other Agent Skills runtimes). It turns an agent into a careful family-history researcher for the former USSR, the Soviet Union and the Russian Empire. The agent reads church books and civil records, military, deportation and repression files, and unindexed archive scans. It keeps every find traceable, separates records from interpretation and says plainly what is proven and what is not.

The skill's instructions are written in Russian, but the agent talks to you in your language: English, Ukrainian, Russian, Polish, German and so on. It quotes sources in their original spelling with a translation, and builds search queries in the languages of the records.

What it does

• Case intake and scope. One research question, known facts, who may be alive, what is off-limits.
• Reproducible registers. Persons, artifacts, claims, relationships and a full search log (CSV), plus a final report template.
• Historical jurisdiction model. It resolves every event to the state, province, district, parish or civil registry as of the event date, not today's map.
• Name-variant matrices. Pre-reform Russian, Ukrainian, Polish, Romanian, German and Yiddish forms, patronymics, maiden names and transliterations.
• Source strategy. Originals first, then official catalogs, indexes, published document collections, and only then trees and forums as leads.
• Evidence protocol. Claims get explainable statuses, not percentages: hypothesis, single-source, corroborated, strongly-corroborated, contradicted, unresolved. Copies and mirrors of one record share an independence_group, so they never count as independent proof.
• Identity resolution. Namesakes stay separate person_ids until distinguishing evidence appears: house number, parents, godparents, exact birth date or military unit.
• Audit script. It checks referential integrity and flags weak corroboration before you write conclusions.
• Final report. Every relationship is laid out edge by edge, with contradictions, failed searches and concrete next steps.

Field lessons (new in 1.1.0)

Version 1.1.0 adds references/field-lessons.md, distilled from a real multi-week research case. Personal data from that case is not included.

• Unindexed scans. Most ex-USSR church books on FamilySearch are images only. The file shows how to find the right film (including archive-reference-to-film mapping), map it, skim the key column and zoom on candidates. It also covers what to log.
• Reading cues that link records.
  • An exact birth date in a marriage register can match a baptism day for day.
  • House numbers persist for decades.
  • Stillbirths are listed among births.
  • Patronymic formulas: Ukrainian possessive forms, Romanian fiul lui / n., Church Slavonic, German.
  • Clerk name swaps, such as Grigorie and Gheorghe.
• Marginal annotations. Later Soviet-era notes on old registers show when a certificate was issued, which is evidence that the person or their family was alive and requesting documents.
• Repression and deportation records.
  • Published document collections and their typical contents.
  • How rehabilitation books group people.
  • How to read a "basis" column such as a 25-year sentence.
  • Why a family is linked to a deportation operation, not to the local incident used to justify it.
  • How to draft an archive request.
• Military databases. WWII loss records (survivors are absent), "surname nests" built from birthplace clusters, and which portals put up CAPTCHAs. Austro-Hungarian WWI casualty lists help for Galicia and Bukovina.
• Places that no longer exist. Liquidated hamlets, redrawn districts, and the difference between "born in" and "grew up in". Also archives in occupied or war-damaged areas.
• Family materials as sources. Passports, oral-history recordings with timestamps, and the user's own notes, all tagged by source type.
• Browser technique. Deep-zoom tile crops, composite column views for fast skimming, keeping long jobs in their own tab, polite crawling and retries.
• Knowing when to stop. When public sources are exhausted, the agent says so once, prepares questions for living relatives and request drafts for archives, and does not invent or loop.

Also in 1.1.0:

• The agent replies in the user's language; the intake template defaults to requested_output_language: auto.
• The skill description is bilingual, so it triggers for English-speaking users too.
• CAPTCHAs are handed to a human. The agent never solves or bypasses them, and the user signs in to sites themselves.
• More seed sources, each with a reliability class and role.
• New eval cases: language matching, unindexed scans, house-number identity, birthplace conflicts, exhausted sources, repression lists.

Install

Clone the repository into your agent's skills folder:

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

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

For a single project, put the folder in .claude/skills/ inside the repository. The scripts need only Python 3 and the standard library.

Use

Just describe the family question; the skill triggers on genealogy requests. 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."

The agent will set up a case folder:

python scripts/init_case.py --case-dir ./my-case --research-question "Who were Maria's parents?" --subject-label "Maria"
python scripts/hash_artifact.py ./scans/marriage-1902.jpg     # SHA-256 for every saved artifact
python scripts/audit_evidence.py --case-dir ./my-case          # check registers before the final report

Repository layout

SKILL.md                         main instructions (workflow, hard rules, language policy)
references/
  source-strategy.md             source hierarchy, query patterns, catalogs, archive requests
  evidence-protocol.md           artifact assessment, statuses, identity resolution, conflicts
  ex-ussr-locale-guide.md        jurisdictions, name variants, calendars, record types by period
  browser-and-captcha.md         browsing, sign-in, CAPTCHA hand-off, rate limits
  privacy-and-safety.md          living people, minors, DNA, sensitive findings
  seed-sources.md                curated starting resources with reliability classes
  field-lessons.md               practical lessons from a real case (new in 1.1.0)
assets/                          case intake, CSV registers, final report template
scripts/                         init_case.py, hash_artifact.py, audit_evidence.py
evals/discovery-and-logic.yaml   trigger and reasoning test cases

Responsible use

• Family history, not surveillance. The skill refuses to look up current addresses, phones or accounts of living people, and it minimizes their data in reports.
• No bypassing. No CAPTCHA solving, no paywall, geo-block or 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. Always check the current official procedure before sending a request; the skill only drafts requests, it does not send them.

Contributing

New sources are welcome. Add them to references/seed-sources.md with these fields: owner, jurisdiction, collection type, originals or index, stable IDs, access, restrictions, typical errors, date last checked. Please keep personal data out of examples.

License

MIT © 2026 Denis Shiryaev.

Maintained by Denis Shiryaev (@DenisSergeevitch).