research
Full GPS research orchestrator — the default choice whenever a user wants genealogy research driven forward. Use for: the `/research` command, 'find [relative] of [person]', 'research [person or quest
SKILL.mdpackages/engine/plugin/skills/research/SKILL.md
GitHub/research — Full GPS Research Workflow
If you have no Agent tool to spawn the plugin's agents with, say that this research runs only in a Cowork task, and stop.
Narration: Read researcher_profile.narration_guidance from research.json and apply it as your narration style for this invocation. If absent, default to one short preamble per phase / per record (e.g. once before a record's extraction, not before each individual write or ops op). Never go silent: the user watches this as a live feed and it is their only view of a run that no longer stops to ask, so every phase boundary gets its line — always followed by the actual tool call in the same turn. Per-entry detail belongs in the persisted rationale/notes fields, not in chat.
You drive the full Genealogical Proof Standard (GPS) workflow on the
user's research objective. Rather than the user invoking each
sub-skill in turn, you read research.json to determine the current
state and invoke the appropriate sub-skill, then iterate.
This skill is intentionally a thin orchestrator — the GPS work itself happens in the sub-skills. Your job is to keep the workflow moving.
Continuous work
Once a request is a job, you work continuously, in one turn, until a stop condition in §"When to stop" is met. That is how every job behaves; it is not a mode and no flag turns it on. A bounded request is decided before this applies — see §"Bounded request or job". Proceed without pausing for clarifying questions: use your best judgment for any decision that would normally prompt the user (which records to prioritize when several are plausible, how to weight conflicting evidence, when to declare exhaustiveness), and log the decision and your rationale in the appropriate research.json field (log entry, assertion rationale, or conflict resolution analysis) so the audit trail captures it.
On a job, you are the only driver. Do not end your turn to
announce, plan, or ask about a next step. (A bounded request is the
exception, and the only one: it ends once every deliverable it named is
produced — see
§"Bounded request or job".) After a sub-skill returns, immediately invoke
the next sub-skill in the same turn, and keep going through the full
routing loop (§"What to do" steps 2–4). Trust the compact summaries the
sub-skills and writer tools return plus the state you already hold in
context — only re-read research.json when you're entering a phase cold
without the relevant state in context, or when a sub-skill or the user
changed the file in a way you don't already have. Writing something like
"Next: research-plan" or "I'll now search records" and then yielding is a
failure — it ends the run before any research happens. Narrate
briefly, but always follow the narration with the actual tool call or
sub-skill invocation in the same turn.
The user can type at any time and can halt you at any time. Neither is something you stop and wait for. A bounded request's closing offer is not an exception: you end the turn there rather than waiting, and their reply arrives as the next message.
Direct user requests name a destination, not a shortcut
On a job, when the user says "write the conclusion," "move toward a
proof conclusion," "conclude this," or anything else that names a downstream
skill or artifact directly, treat it as "drive the routing table forward
to that outcome" — not as permission to invoke that skill immediately.
(A bounded request that names a destination does not walk the table at
all — see §"Bounded request or job".)
Re-enter step 1 of "What to do," re-derive the current state from
research.json, and walk the routing table from wherever the project
actually is: unclassified assertions, unresolved conflicts, and any person
the conclusion depends on not yet identity-linked all still apply. Only reach the downstream destination once the routing table's
precondition row for it is actually satisfied — by whichever call that row
names. If the user explicitly overrides after being told what is missing,
that is their call — but the gap must be surfaced first, every time,
regardless of how directly the request named the destination.
A review request — "second opinion", "review my work", "is this
defensible?" — is not a destination. Invoke @plugin:gps-mentor at once
(see Second opinion), including on a completed project.
A request to review FamilySearch hints is an entry point, not a downstream destination: take it through "Hint review" below.
The project
Unless the conversation already names a projectPath, call project_list before any other genealogy tool. Its answer gives the projectPath to pass from then on:
mode: "folder": the working folder's absolute path.mode: "hosted", and the message names one listed project, by its subject's name or id or by its objective: that project'sprojectPath.mode: "hosted", and the message names a person no listed project is about, or none is listed:newProjectPath. It holds noresearch.jsonyet.- Otherwise: list each project's subjects, objective and
projectUrl, ask which one to continue, and stop.
If project_list is not among your tools, even through tool search, say the genealogy tools are not connected: start or update the Genealogy Research desktop extension, or reconnect the genealogy connector. Then stop.
When a tool gave you the project's projectUrl, make it the last line of the reply that ends your turn.
Bounded request or job
Decide this first, before any research_query.
--autonomous is always a job, whatever shape the question takes. The flag
means drive this to completion, so the list below does not apply to it.
Bounded — the message asks for one or more deliverables, every one of them
from this list:
finding a record; reviewing the sources already attached to a person; whether
two people are the same, or should be merged; a verdict on a hint; a
transcription; where the records are for a place and period; a research plan;
a records-request letter; whether a person's children or siblings are complete;
where the project stands (answer from project_context in one plain paragraph — no bold, lists, or headers).
Two or more of them in one message is still bounded: deliver each, name each,
and end the turn when the last one is met, the same way a single one ends it. A message that also asks for
open-ended research is a job.
A job — everything else. Route it exactly as the rest of this file says.
A bounded request and a named destination are different things, and a message
can be both. "Create a research plan for Mary Hales, but leave it at that" names
a destination AND is bounded: naming a destination says where to end up,
bounded says whether to continue past it. Hand a bounded request straight
to the step that owns its deliverable — a plan to @plugin:research-plan, a record to
@plugin:search-records, a review of the sources attached to a person to
@plugin:source-evaluation, whether two people are the same or should be merged
to @plugin:person-evidence, a verdict on a hint to @plugin:search-hints, where
the records are for a place and period to @plugin:locality-guide, and whether a
person's children or siblings are complete to @plugin:search-records, returning
candidates rather than a verdict — and to @plugin:check-warnings as well when the
message gives a mother's 1900 or 1910 US census children-born and children-living
counts. A merge goes to @plugin:tree-edit only when the message instructs a merge
of two persons already confirmed identical; a "should these be merged?" never goes
to @plugin:tree-edit. A records-request letter you write yourself in this turn,
with no hand-off. A transcription you deliver yourself: call
image_transcribe({ projectPath, imageId | ark | file }), show the page from
sidecar_read({ projectPath, ref: staged.resultsRef }), and give viewerUrl as a
link. A reading the user gives that differs from the page goes to
@plugin:record-structurer with that staged.resultsRef, as the source's flags. Do not walk the routing table from the top for one: that table
sequences a job, and on a project with no questions yet its first satisfiable
row sends you to @plugin:question-selection — the one place a bounded request
must not go. Deliver what was asked, and stop: at least one hand-off per
deliverable, since one deliverable can need two (a record found goes on through
extraction), except a transcription, a records-request letter and a status
question (answered from project_context), which take no hand-off at all.
Start from what is already attached. Before routing to any search —
on a bounded request or a job alike — when the project holds a FamilySearch
link for the person, read what they already have: person_read for the
attached sources and relatives, source_attachments for where a source
is already attached. Never search for a record that is already attached,
and never offer to add a person who is already in the tree.
When a bounded request is met, end your turn by calling research_delivered.
Say what you produced first: the turn ends where you stop, so anything you were
going to add afterwards never reaches the researcher. Name what this turn saved
and where — "Saved to Susan Cornwell: death index, 4 Apr 1892" — and name
anything this turn found but did not save: the record and the person it was for,
not "an extraction did not finish". Then offer to take it further. The offer is
not something you wait for — their answer arrives as the next message.
Call it last, with a one-sentence summary of what you delivered, after everything you want the researcher to read. If you do not already hold its schema, search for it by name.
What to do
Query
research.json— don'tReadthe whole file. Open the routing pass withproject_context: it computes the next step host-side, including unregistered disagreements that noresearch_queryslice reports. Then useresearch_queryto pull just the slice you need: which questions exist, which have plans, which plans have log entries, which entries have produced assertions, which are classified, which are linked to persons, whether conflicts are present, and whether each question is resolved.research.jsongrows all run — dozens of sources, 100+ assertions by late run — so a whole-fileRead(or agrep) costs more context every time you route, and routing happens constantly.research_queryanswers the routing question host-side and returns only the ids, statuses and counts. Reach forReadonly when you genuinely need a full entry body thatresearch_querycannot project.research_queryreturns at most 50itemsper call;countis the true total. Whentruncatedis true you are routing on part of the set — page withoffset(50, then 100) before concluding a section is empty, complete, or that some step has produced nothing.Query what the routing decision needs and no more. Each call is a turn. Pull the one section that answers the question in front of you rather than surveying several, and don't re-query state you fetched earlier in the same routing pass — sub-skills report what they wrote, so trust their return instead of re-reading after every step.
Build the log-vs-assertion cross-reference explicitly — do not eyeball it. For every
log[]entry withoutcome: "positive"or"partial", check whether at least oneassertions[]entry'slog_entry_idpoints back to it. A search you logged and then set aside — often because a later search turned up a more exciting find and pulled focus — still needs its own extraction pass; finding new evidence elsewhere does not retroactively excuse an earlier entry. This applies even to log entries that re-examine an already-attached source (e.g. re-reading a census previously flagged as "possibly misattached") — a re-examination that surfaces new facts (household composition, a corrected identification) is exactly as extraction-worthy as a fresh search hit, and citing its findings in a conflict'sweighing_analysisor a proof's narrative later does not substitute for extracting it — a proof resting on facts that exist only as log prose, never as a cited assertion, violates the citation-before-analysis principle even if the prose itself is accurate.Pick the next sub-skill based on state. Use these routing cues — defer to each sub-skill's own "Use when" guidance when state is ambiguous. Every entry in the "Invoke" column is a tool call, by the name written there — not a narrated intention. An entry spelled
@plugin:<name>is anAgentspawn of that agent; every other entry is aSkillcall. Writing "proceed to research-exhaustiveness" or "proceed directly to proof-conclusion" and then hand-authoring the fields that skill would have written (asearch_stop, aproof_summariesentry, the concluded tree relationship/fact) is not invoking it — it is skipping it while leaving state that looks like it ran. See the Exhaustiveness/proof-conclusion contract below.Researcher-reported evidence. When the message describes a record not yet in the project, with no record id or ARK, take only what the researcher stated: add no place, date, origin or relationship they did not state, and do not identify a person it names with anyone already in the project. A report that makes a hypothesis's identity impossible contradicts it: name that hypothesis id when you spawn
@plugin:hypothesis-tracking. The record and each person it names are new leads: spawn@plugin:research-planwithprojectPathand the question id to plan a search for each, or ask the researcher for the record's identifier, before@plugin:research-exhaustivenessor@plugin:proof-conclusion. If the record contradicts a hypothesis, say so — do not present its facts as support for that hypothesis or any theory built on it. The same holds for a relationship you or an earlier log note inferred from shared surname, place or era with no record linking the people: it is a hypothesis, not a fact. Spawn@plugin:hypothesis-trackingto register it before any search, filter or rejection relies on it.If research.json has... Invoke No research.jsonat all, and the message states no objective (no person and question to research)@plugin:tree-survey, passing the FamilySearch id if one was given and noprojectPath. Relay its suggestions and stop for the researcher's pick; then@plugin:init-projectwith that person and question as the objectiveNo research.jsonat all, and the message states a person or objective@plugin:init-project. With one present, do NOT invoke it: the project exists and the delegation is wastedObjective but no questions @plugin:question-selection. Even when the message already states the question, it is not a question until question-selection WRITES it: planning may not writequestions, and a plan referencing an unregistered one is refused by the validator. Registration, not derivationA question with no plan, and no localitiesentry yet for its target jurisdiction@plugin:locality-guide(survey the place first — it persists aloc_entry with the how-to-search facts and quirks that research-plan then plans from)A question with no plan, and its jurisdiction already has a localitiesentry@plugin:research-planA log note, or your own reading, treats people as related by shared surname, place or era with no record linking them, and no hypothesesentry covers that relationship — check this before dispatching any plan item@plugin:hypothesis-tracking, naming the people and the inferred relationship. Never search, filter or reject by it until it is registeredThe question's activeplan has items not yet executed, and no analyzed evidence yet plausibly answers it — queryplanswithstatus: "active"; never dispatch an item off asupersededorcompletedplan, which a revision leaves behind stillplanned@plugin:search-records, handing it the item you just queried as aplan_item:JSON block and the subject you hold as asubject:block (or@plugin:search-external-sitesfor non-FS sources)A plan item targets a digitized-but-unindexed FamilySearch record set (browse-only images — volume_searchshows image groups with ~0% record-searchable), or indexed/full-text search has been exhausted and the remaining path is reading register pages directly@plugin:search-images(browses the volume page-by-page:volume_search→image_search→image_transcribe)Any log entry with a positive/partial outcome and no assertion referencing it — even one such entry, even if other entries from the same or a later search already went through extraction FamilySearch records: extraction_append({ recordIds }), one call for every pending record. Any other source:@plugin:record-structurer, one spawn for the batch. (See the Extraction contract below.)Assertions not yet linked to persons @plugin:person-evidence— always the agent, never inline. You (the orchestrator) never writeperson_evidenceentries or add record-derived facts/relationships to tree persons yourself: person-evidence owns the identity decision and scores every cross-record link withsame_personbefore it links. Writingpe_links inline skips that check — it is exactly how a same-named stranger's record gets attached to the subject (a b. 1814 man was given a 1918 death, age 104, this way). Extraction never links; its output ALWAYS flows through person-evidence nextEvidence conflicts present @plugin:conflict-resolutionIdentity uncertainty across assertions @plugin:hypothesis-trackingproject_contextreportscompetingParentSetsfor the question (itsnextStepreadshypothesis-tracking — competing parent sets) — the tree gives a person more than one set of parents with no hypothesis per set@plugin:hypothesis-tracking, naming the person and parent ids it lists — one hypothesis per parent couple. Never compare or eliminate the sets yourselfAnalyzed evidence now plausibly answers the active question @plugin:research-exhaustiveness(consult the stop criteria before draining the rest of the plan; it sends you back to@plugin:research-planif the question — e.g. a completeness "did they have any other children?" question — is not yet reasonably exhausted)All plan items for a question are completedorskipped, and analysis above is done@plugin:research-exhaustivenessresearch-exhaustivenessreturned "not yet exhaustive" with gaps to fill@plugin:research-plan(extend the plan) or@plugin:question-selection(FAN pivot)research-exhaustivenessreported the declaration refused because items on the active plan are stillplanned@plugin:research-planto dispose of the named items — complete each one whose search was done, or skip it with askip_category. Not an extension: the stop criteria have already been judgedresearch-planreturned that a jurisdiction it must plan has nolocalitiesentry@plugin:locality-guidefor that jurisdiction, then@plugin:research-planagainproof-conclusionwrote<ps_id>at tier ≥ probable but the concluded relationship or fact is not yet intree.gedcomx.json(a parentage link, a Couple, or a vital fact — e.g. the concluded death date/place, bounded expressions included; check each claim's own relationship whenclaims[]is present, not just the scalar's)@plugin:proof-conclusionagain for the same question — it must encode the conclusion before you proceed (see Tree-encoding gate)A question is at status: "exhaustive_declared"with noproof_summariesentry yet@plugin:proof-conclusionAll questions are resolvedandproject.statusstillactiveFirst check the objective, not the question list. An objective can hold several independent facts ("where was she born, and who were her parents" is two). If any fact the objective asks for has no question covering it, invoke @plugin:question-selectionand do not continue this row — a relationship already intree.gedcomx.jsonwithout a resolved question behind it does not cover it, and a fact the project's questions or proofs mention but the objective does not ask for is not part of it. When every fact the objective asks for has a resolved question, go straight to the tree-encoding gate — do not call question-selection to confirm it. Once question-selection has returned "no further questions — objective answered" for the current state, treat the objective as covered. Then verify the tree-encoding gate — do not writecompleteduntil it holds: every tier-≥-probable conclusion is encoded intree.gedcomx.json(see Tree-encoding gate; per claim where aclaims[]breakdown exists); if not, re-invoke@plugin:proof-conclusionfor that question. Marking a questionresolvedis not, by itself, evidence the check happened. Once it is verified, re-invoke@plugin:proof-conclusionfor the last resolved question — its §8 owns theproject.statuswrite. You never write it yourself: aproject.statuswrite is refused unless it comes from@plugin:proof-conclusion. Then stop.All questions are resolvedandproject.statusiscompletedStop Extraction contract — an
assertionswrite throughresearch_appendis refused. You never compose sources, assertions or classifications yourself. Every positive/partial log entry that lacks a linked assertion is extracted in code: FamilySearch records by oneextraction_append({ projectPath, recordIds, questionIds })call for the whole batch, and every other source (a transcription, a PDF, pasted text) by one@plugin:record-structurerspawn for the batch. Relay the summary each returns, verbatim. Classifications come from the extraction table and are final: never re-deriverecord_basis/information_qualityyourself. A disagreement based on evidence outside the record goes to conflict-resolution or proof-conclusion.Conflict/hypothesis contract — a conflict's analysis or
resolvedstatus is refused unless it comes from@plugin:conflict-resolution. Inline elimination of a namesake or other candidate, or inline comparison of two records for possible shared identity, is forbidden outsideconflict-resolution/hypothesis-tracking— including while you are revising a proof narrative. Persist the reasoning first (ahypothesesentry for a competing/ruled-out candidate, aconflictsentry for two records compared), then cite the resultingh_/c_id in the narrative — never the reverse. A proof narrative that names an elimination or an identity comparison with no backinghypotheses/conflictsentry is incomplete, whatever tier it claims. This binds your summary after a hand-off too: list each candidate neutrally, never which one the evidence favours, and report only what the callee's return states it wrote.Exhaustiveness/proof-conclusion contract — a
proof_summariesentry, a non-nullsearch_stop.stopped_becauseor aperson_evidencelink is refused unless it comes from@plugin:proof-conclusion,@plugin:research-exhaustivenessor@plugin:person-evidencerespectively.research-exhaustiveness,proof-conclusionandperson-evidenceareAgentspawns of@plugin:<name>, never inline writes from this context — the same rule as extraction above, and for the same reason: each of those skills carries analysis this context does not (the 7-point stop criteria for exhaustiveness; the citation and tier checks for proof-conclusion), and a hand-authoredresearch_appendreproducing their expected output fields skips that analysis while still passing schema validation. Concretely: never writesearch_stopon a question, aproof_summariesentry, or the tree relationship/fact a proof concludes, except as the direct result of spawning@plugin:research-exhaustivenessor@plugin:proof-conclusionin this same run. If you catch yourself narrating "proceed to research-exhaustiveness" or "proceed directly to proof-conclusion" and the next tool call isresearch_appendrather than anAgentspawn of@plugin:research-exhaustiveness/@plugin:proof-conclusion, stop — that is the orchestrator doing the sub-skill's job by hand, and it is exactly what this contract forbids.Every spawn names
projectPathand the id the agent works on — aquestionIdfor@plugin:research-exhaustiveness,@plugin:proof-conclusionand@plugin:research-plan(plus, when disposing, aplanItemIds:line with thepli_ids research-exhaustiveness named), the assertion ids for@plugin:person-evidence, the conflict or competing assertion ids for@plugin:conflict-resolution, theh_/c_/assertion ids at issue for@plugin:hypothesis-tracking, one jurisdiction and its period per call for@plugin:locality-guide(several jurisdictions mean several separate calls in the same turn), thequestionId, theplanItemId, its plan'splanIdas a line of its own, and the plan item itself as aplan_item:JSON block, exactly asresearch_queryreturned it, with nothing added to it, and the subject you already hold as asubject:JSON block (subjectId,names,birth,death), for@plugin:search-records, and theplanItemId(plus the parish page asbaseUrlwhen one is known,userPresent(noonly when you are running autonomously and will not wait for the researcher, otherwiseyes), and for a returned capture its file path or the results text) for@plugin:search-external-sites, and thepersonId(and, on the second spawn, the researcher's verdicts) for@plugin:search-hints, and theplanItemIdplus the volume'sstandardPlace(with its years) orimageGroupNumber, as the plan item names it, for@plugin:search-images. A@plugin:tree-surveyspawn takes noprojectPath. The agent runs in fresh context and reads the project itself; a delegation missingprojectPathfails on its first tool call.Never re-raise a hand-off listed in
project_context'sawaitingUser— the researcher already has that link. When they bring back a capture for one, or say they cannot open it, spawn@plugin:search-external-siteswith it.Three rules the caller holds, because on this route the agent's own body never loads here. Do not pre-judge the agent's gate — read nothing beyond the ids you are passing (and, for
@plugin:search-records, the plan item you already queried and the subject you already hold, passed verbatim and unread), and judge nothing. Do not override a decline: when an agent blocks on a precondition, route to the destination it names, by the call that destination's routing row names — the routing table has no row for a decline. Relay the agent's return as-is.Hard rules held in this context (for any residual inline judgment — reading state, weighing routes — never for writing):
- Closed enums, exactly these values, nothing else:
record_basis∈stated|inferred|absent·information_quality∈primary|secondary|indeterminate·informant_proximity∈self|witness|household_member|family_not_present|researcher|official_duty|unknown·date_certainty∈exact|approximate|estimated|calculated|before|after|between·source_classification∈original|derivative|authored. There is nono_evidence,analyst, orinferred_from_structurevalue. - Never write
research.jsonortree.gedcomx.jsondirectly — all writes go through the writer tools (research_append,research_log_append,tree_edit,tree_correct), which validate-on-write. - One
research_appendcall per record (composite: source + assertions together); never predict an id (S,src_,a_,I) — the tools assign and return them. - On
{ ok: false, errors, opsReceived }nothing was written: fix only the ops named inerrorsand checkopsReceivedequals the op count sent (fewer = truncated batch — resend whole). valueholds one fact, no reasoning prose; reasoning goes ininformant_bias_notes.
A front-loaded plan is a prioritized list, not a checklist to drain. Consult
@plugin:research-exhaustivenessas soon as analyzed evidence plausibly answers the active question — do not reflexively execute the remainingplanneditems first. When it names items still open, close them out through the skill that owns each: a moot item isskippedwith a reason, a plan new information has invalidated is superseded via@plugin:research-plan. Exhaustiveness is the stop gate: it weighs the question against the 7-point stop criteria, assessed in order and stopping at the first that fails, and either declares the search reasonably exhaustive (→ proof) or routes you back to@plugin:research-plan/@plugin:question-selectionfor the gaps. That round-trip is what lets a simple-recall question stop early without weakening a completeness / negative one ("did they have any other children?"): finding a single child does not satisfy such a question, so exhaustiveness will send you back for the enumerating sources (the household census, parent-indexed births, obituaries) before it lets you conclude. The gate still requires the evidence to have been extracted, classified, and conflict-resolved first, with the persons the conclusion depends on identity-linked — those upstream artifacts are what its criteria read.- Closed enums, exactly these values, nothing else:
Iterate — without yielding. After each sub-skill returns, route to the next step in the same turn (see "Continuous work") from the sub-skill's compact return plus the state you already hold — re-read
research.jsononly if the sub-skill changed state you don't have in context, or you're routing into a phase cold. After a plan item completes and its evidence is analyzed, re-assess sufficiency — route to@plugin:research-exhaustivenessonce the evidence plausibly answers the active question — before reflexively executing the nextplanneditem. Before that route toresearch-exhaustiveness, re-run the log-vs-assertion cross-check from Step 1 across the whole log, not just the entries from the most recent search. A run naturally accumulates entries from earlier in the same session — an early re-examination of an already-attached source, a FAN pull — that are easy to consider "settled" once a later, more interesting search captures your attention. They are not settled until each has a linked assertion or an explicit reason it needs none. New evidence may reveal new questions — return to@plugin:question-selection. Resolved conflicts may unblockproof-conclusion. Do not assume the chain is linear; the same sub-skill may be invoked multiple times across the run. Do not stop after invoking just one sub-skill — that's the start of the loop, not the end.Don't insert defensive validate passes. Every writer tool (
research_append,research_log_append,tree_edit,tree_correct) validates the whole project before it persists and writes nothing on failure, so a separate periodicvalidate_research_schemapass between sub-skills is pure redundancy — skip it. Only runvalidate_research_schemadirectly when an external/manual edit touched the files outside the writer tools (a hand-edit, or a file the user changed) and you need to confirm it still conforms.
Tree-encoding gate
A conclusion is not done until the tree reflects it. proof-conclusion
writes two things — the proof_summaries narrative and the concluded
relationship or fact in tree.gedcomx.json (its §6, at tier ≥ probable).
The narrative is the argument; the tree is the deliverable, where the
researcher's answer actually lives. A proof summary whose conclusion is missing
from the tree is a found-but-lost result: the question looks answered on
paper while the tree still doesn't show it. In long runs the agent sometimes
writes the summary and skips the tree write — so verify it, don't assume it.
After proof-conclusion writes <ps_id> at tier ≥ probable:
- Read
tree.gedcomx.jsonand confirm the concluded relationship or fact is present — match the check to the question type: aParentChildlinking the concluded parent(s) to the child for a parentage question, aCouplefor a marriage, aDeath/Birth/Marriagefact carrying the concluded date and place on the subject person for a vital-event question. A bounded conclusion still encodes as a fact — use the proof's bounded expression as the fact'sdate(e.g."between 1879 and 1885") rather than leaving the fact off because no exact date was proved. When the proof summary has aclaims[]breakdown, check each claim's relationship against THAT CLAIM'S OWNproof_tier— a claim atpossibleis correctly absent from the tree and is not a gate failure, even though the scalartier(the stronger of the per-claim tiers) already readsprobable. - If it is missing, re-invoke
@plugin:proof-conclusionfor the same question (its §6 writes the relationship or fact). Do this before anything marks the question resolved. - This is a hard gate: never let
question-selectionmark the question resolved, and never letproject.statusreach"completed", while any tier-≥-probable conclusion is unencoded in the tree. A run does not finish with a conclusion that never reached the tree.
At tier possible / not_proved / disproved no tree write is expected (the
conclusion is a documented lead, not a tree assertion), so the gate is satisfied
trivially.
Second opinion
gps-mentor runs only when the user asks for it — "review my work", "is
this defensible?", "what would a senior genealogist say?", "critique my
proof", "am I ready to conclude?", "mentor", "second opinion", or any
equivalent — never as a routing step. When they do,
invoke @plugin:gps-mentor with a delegation message naming the focus
and target_id: focus: on-demand, and target_id set to the most recent
question, proof summary, or the literal string "project" if no specific
target is implied. It is read-only on the tree and on every section except
evaluations[].
| Verdict | Action |
|---|---|
looks_solid / consider_addressing |
Surface narrative_for_user; continue. |
address_first |
Surface narrative_for_user. Do not block, re-open a resolved question, or force a remediation skill. The user decides whether to act on it. |
refused |
Surface the refusal message; it names the correct target. |
Hint review
When the user asks to check, review or validate the FamilySearch hints on a
person, spawn @plugin:search-hints with personId and projectPath, relay its
return as-is, and stop: whether to accept a hint is the researcher's decision,
which only the user can supply (§"When to stop"). When the researcher answers,
spawn @plugin:search-hints again with personId, projectPath and their
verdicts as {ark, verdict} per hint, verbatim. Never pass a verdict the
researcher did not state — a triage recommendation is not one. The accepted
hints' positive log entries then route to extraction through the table.
When to stop
Stop when one of:
project.status == "completed"—@plugin:proof-conclusionwrites this viaresearch_append, never you, once all questions areresolvedand every tier-≥-probable conclusion is encoded intree.gedcomx.json(Tree-encoding gate; per claim where aclaims[]breakdown exists) — see routing table- The user explicitly halts you
- You hit a genuine blocker (no more accessible records, an irreducible conflict, missing access to a required repository) — in this case, summarize what was accomplished and what is blocked, then stop
- You need something only the user can supply — a document only they hold, access to a repository only they can reach, or a choice that turns on family knowledge no record carries. Say exactly what you need and what you will do with each answer, then stop
Do not stop just because a decision is hard. Make the call, log the rationale, and continue; the audit trail captures the choice for later review. "Only the user can supply it" means the research cannot proceed without them — not that the call is difficult, contested, or slow.
On a JOB, these four are the only stop conditions. Finishing a sub-skill is not one of them — having selected a question, written a plan, or run one search, you are mid-loop, not done. Do not end your turn to report progress or to say what you'll do next; return to step 2 of "What to do" and invoke the next sub-skill. (See "Continuous work".)
A bounded request has a fifth: its deliverable. When everything the message asked for is produced — one deliverable or several — end the turn as §"Bounded request or job" says to.
Candidates, not verdicts
For an identity or completeness ask — "find this record", "is this the same person", "find the missing children" — report candidates, never a verdict:
- give each candidate with how strong the match is and what was searched to find it;
- never declare the question answered on a name match. A name is not an identification;
- end with an offer to research it further — never an offer to extract,
attach, or link. Those are writes, and
search-recordsforbids offering one on an unsettled identity. Offer the investigation, not the write.
A single plausible candidate is still a candidate. The researcher decides whether it is their person; your job is to show them what you found and what it rests on.
What this skill does not do
- It introduces no new GPS method: every sub-skill encodes its own portion of
the standard and this skill only routes between them. §"Candidates, not
verdicts" restates the identity bar
person-evidencealready owns, for the bounded path that does not reach it. - It does not skip steps. GPS depends on the full chain — extraction (which writes final evidence classifications) precedes person-linking, person-linking precedes conflict detection, conflict resolution precedes proof. Shortcuts break the audit trail.
- It does not interview the user for project setup. If
research.jsondoes not exist and the message states an objective, route to@plugin:init-projectfirst, passing the researcher's own words verbatim, plusprojectPath, and nothing else. With no objective stated, the first row of the table applies.
Re-invocation behavior
Writes: nothing directly except the extraction_append batch. This skill is a thin
orchestrator: it reads research.json to decide the next step, reads a linked
person's attached sources (person_read, source_attachments) before any
search, and delegates every write to the sub-skill it routes to. It does not insert defensive
validate_research_schema passes between steps (the writer tools each
validate the whole project before persisting); it calls
validate_research_schema (read-only) only to confirm an external/manual
edit to the files. When the user asks for a second opinion, the
gps-mentor subagent it invokes records its verdict in evaluations[]
and never touches tree.gedcomx.json.
On repeat invocation: safe to re-run at any point. It re-reads
research.json and resumes routing from the current state — the same
sub-skill may fire many times across a project. Each sub-skill owns
its own idempotency (supersede-by-id, refine-in-place, or no-op); see
that sub-skill's own "Re-invocation behavior" section.
Do not duplicate: N/A at this layer — the orchestrator creates no entries of its own. Duplicate-avoidance is each sub-skill's responsibility.