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.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's projectPath.
  • mode: "hosted", and the message names a person no listed project is about, or none is listed: newProjectPath. It holds no research.json yet.
  • 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

  1. Query research.json — don't Read the whole file. Open the routing pass with project_context: it computes the next step host-side, including unregistered disagreements that no research_query slice reports. Then use research_query to 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.json grows all run — dozens of sources, 100+ assertions by late run — so a whole-file Read (or a grep) costs more context every time you route, and routing happens constantly. research_query answers the routing question host-side and returns only the ids, statuses and counts. Reach for Read only when you genuinely need a full entry body that research_query cannot project.

    research_query returns at most 50 items per call; count is the true total. When truncated is true you are routing on part of the set — page with offset (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 with outcome: "positive" or "partial", check whether at least one assertions[] entry's log_entry_id points 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's weighing_analysis or 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.

  2. 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 an Agent spawn of that agent; every other entry is a Skill call. Writing "proceed to research-exhaustiveness" or "proceed directly to proof-conclusion" and then hand-authoring the fields that skill would have written (a search_stop, a proof_summaries entry, 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-plan with projectPath and the question id to plan a search for each, or ask the researcher for the record's identifier, before @plugin:research-exhaustiveness or @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-tracking to register it before any search, filter or rejection relies on it.

    If research.json has... Invoke
    No research.json at 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 no projectPath. Relay its suggestions and stop for the researcher's pick; then @plugin:init-project with that person and question as the objective
    No research.json at 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 wasted
    Objective 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 write questions, and a plan referencing an unregistered one is refused by the validator. Registration, not derivation
    A question with no plan, and no localities entry yet for its target jurisdiction @plugin:locality-guide (survey the place first — it persists a loc_ 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 localities entry @plugin:research-plan
    A log note, or your own reading, treats people as related by shared surname, place or era with no record linking them, and no hypotheses entry 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 registered
    The question's active plan has items not yet executed, and no analyzed evidence yet plausibly answers it — query plans with status: "active"; never dispatch an item off a superseded or completed plan, which a revision leaves behind still planned @plugin:search-records, handing it the item you just queried as a plan_item: JSON block and the subject you hold as a subject: block (or @plugin:search-external-sites for non-FS sources)
    A plan item targets a digitized-but-unindexed FamilySearch record set (browse-only images — volume_search shows 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 write person_evidence entries or add record-derived facts/relationships to tree persons yourself: person-evidence owns the identity decision and scores every cross-record link with same_person before it links. Writing pe_ 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 next
    Evidence conflicts present @plugin:conflict-resolution
    Identity uncertainty across assertions @plugin:hypothesis-tracking
    project_context reports competingParentSets for the question (its nextStep reads hypothesis-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 yourself
    Analyzed 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-plan if 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 completed or skipped, and analysis above is done @plugin:research-exhaustiveness
    research-exhaustiveness returned "not yet exhaustive" with gaps to fill @plugin:research-plan (extend the plan) or @plugin:question-selection (FAN pivot)
    research-exhaustiveness reported the declaration refused because items on the active plan are still planned @plugin:research-plan to dispose of the named items — complete each one whose search was done, or skip it with a skip_category. Not an extension: the stop criteria have already been judged
    research-plan returned that a jurisdiction it must plan has no localities entry @plugin:locality-guide for that jurisdiction, then @plugin:research-plan again
    proof-conclusion wrote <ps_id> at tier ≥ probable but the concluded relationship or fact is not yet in tree.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 when claims[] is present, not just the scalar's) @plugin:proof-conclusion again for the same question — it must encode the conclusion before you proceed (see Tree-encoding gate)
    A question is at status: "exhaustive_declared" with no proof_summaries entry yet @plugin:proof-conclusion
    All questions are resolved and project.status still active First 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-selection and do not continue this row — a relationship already in tree.gedcomx.json without 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 write completed until it holds: every tier-≥-probable conclusion is encoded in tree.gedcomx.json (see Tree-encoding gate; per claim where a claims[] breakdown exists); if not, re-invoke @plugin:proof-conclusion for that question. Marking a question resolved is not, by itself, evidence the check happened. Once it is verified, re-invoke @plugin:proof-conclusion for the last resolved question — its §8 owns the project.status write. You never write it yourself: a project.status write is refused unless it comes from @plugin:proof-conclusion. Then stop.
    All questions are resolved and project.status is completed Stop

    Extraction contract — an assertions write through research_append is 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 one extraction_append({ projectPath, recordIds, questionIds }) call for the whole batch, and every other source (a transcription, a PDF, pasted text) by one @plugin:record-structurer spawn for the batch. Relay the summary each returns, verbatim. Classifications come from the extraction table and are final: never re-derive record_basis / information_quality yourself. A disagreement based on evidence outside the record goes to conflict-resolution or proof-conclusion.

    Conflict/hypothesis contract — a conflict's analysis or resolved status 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 outside conflict-resolution / hypothesis-tracking — including while you are revising a proof narrative. Persist the reasoning first (a hypotheses entry for a competing/ruled-out candidate, a conflicts entry for two records compared), then cite the resulting h_/c_ id in the narrative — never the reverse. A proof narrative that names an elimination or an identity comparison with no backing hypotheses/conflicts entry 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_summaries entry, a non-null search_stop.stopped_because or a person_evidence link is refused unless it comes from @plugin:proof-conclusion, @plugin:research-exhaustiveness or @plugin:person-evidence respectively. research-exhaustiveness, proof-conclusion and person-evidence are Agent spawns 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-authored research_append reproducing their expected output fields skips that analysis while still passing schema validation. Concretely: never write search_stop on a question, a proof_summaries entry, or the tree relationship/fact a proof concludes, except as the direct result of spawning @plugin:research-exhaustiveness or @plugin:proof-conclusion in this same run. If you catch yourself narrating "proceed to research-exhaustiveness" or "proceed directly to proof-conclusion" and the next tool call is research_append rather than an Agent spawn 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 projectPath and the id the agent works on — a questionId for @plugin:research-exhaustiveness, @plugin:proof-conclusion and @plugin:research-plan (plus, when disposing, a planItemIds: line with the pli_ ids research-exhaustiveness named), the assertion ids for @plugin:person-evidence, the conflict or competing assertion ids for @plugin:conflict-resolution, the h_/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), the questionId, the planItemId, its plan's planId as a line of its own, and the plan item itself as a plan_item: JSON block, exactly as research_query returned it, with nothing added to it, and the subject you already hold as a subject: JSON block (subjectId, names, birth, death), for @plugin:search-records, and the planItemId (plus the parish page as baseUrl when one is known, userPresent (no only when you are running autonomously and will not wait for the researcher, otherwise yes), and for a returned capture its file path or the results text) for @plugin:search-external-sites, and the personId (and, on the second spawn, the researcher's verdicts) for @plugin:search-hints, and the planItemId plus the volume's standardPlace (with its years) or imageGroupNumber, as the plan item names it, for @plugin:search-images. A @plugin:tree-survey spawn takes no projectPath. The agent runs in fresh context and reads the project itself; a delegation missing projectPath fails on its first tool call.

    Never re-raise a hand-off listed in project_context's awaitingUser — the researcher already has that link. When they bring back a capture for one, or say they cannot open it, spawn @plugin:search-external-sites with 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 no no_evidence, analyst, or inferred_from_structure value.
    • Never write research.json or tree.gedcomx.json directly — all writes go through the writer tools (research_append, research_log_append, tree_edit, tree_correct), which validate-on-write.
    • One research_append call 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 in errors and check opsReceived equals the op count sent (fewer = truncated batch — resend whole).
    • value holds one fact, no reasoning prose; reasoning goes in informant_bias_notes.

    A front-loaded plan is a prioritized list, not a checklist to drain. Consult @plugin:research-exhaustiveness as soon as analyzed evidence plausibly answers the active question — do not reflexively execute the remaining planned items first. When it names items still open, close them out through the skill that owns each: a moot item is skipped with 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-selection for 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.

  3. 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.json only 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-exhaustiveness once the evidence plausibly answers the active question — before reflexively executing the next planned item. Before that route to research-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 unblock proof-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.

  4. 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 periodic validate_research_schema pass between sub-skills is pure redundancy — skip it. Only run validate_research_schema directly 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:

  1. Read tree.gedcomx.json and confirm the concluded relationship or fact is present — match the check to the question type: a ParentChild linking the concluded parent(s) to the child for a parentage question, a Couple for a marriage, a Death/Birth/Marriage fact 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's date (e.g. "between 1879 and 1885") rather than leaving the fact off because no exact date was proved. When the proof summary has a claims[] breakdown, check each claim's relationship against THAT CLAIM'S OWN proof_tier — a claim at possible is correctly absent from the tree and is not a gate failure, even though the scalar tier (the stronger of the per-claim tiers) already reads probable.
  2. If it is missing, re-invoke @plugin:proof-conclusion for the same question (its §6 writes the relationship or fact). Do this before anything marks the question resolved.
  3. This is a hard gate: never let question-selection mark the question resolved, and never let project.status reach "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-conclusion writes this via research_append, never you, once all questions are resolved and every tier-≥-probable conclusion is encoded in tree.gedcomx.json (Tree-encoding gate; per claim where a claims[] 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-records forbids 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-evidence already 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.json does not exist and the message states an objective, route to @plugin:init-project first, passing the researcher's own words verbatim, plus projectPath, 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.