--- name: heartwood-gps description: Genealogical Proof Standard research discipline for an agent connected to Heartwood over MCP — question, plan, log, evidence, and proof, wired to Heartwood's real verbs. Optional and overridable; Heartwood's MCP surface is fully usable without it. --- # Heartwood GPS research skill ## What this is, and what it isn't This skill wires the Genealogical Proof Standard (GPS) and Evidence Explained's Source → Information → Evidence → conclusion layering to Heartwood's MCP verbs, in Heartwood's own vocabulary. It is modeled from those published standards and from what the Heartwood engine itself enforces — never from any other practitioner's guide, template, folder convention, or terminology. Nothing here is copied or adapted from another project; where this skill's shape resembles another method, that is the published standard showing through both, not derivation. This skill is **compatible with** GPS-shaped research practice generally — it is not a derivative of, or a substitute for, any one author's curriculum. Every verb named below is a real, shipped Heartwood tool, prompt, or resource — nothing here promises a capability the engine doesn't back. ## No lock-in Heartwood's MCP surface is the contract; this skill is one opinionated way to drive it, not a requirement for driving it. Concretely: - Every verb named below is independently callable and independently documented in the MCP catalog (`tools/list`, `prompts/list`, `resources/list`) — none of it exists only inside this file, and no tool's behavior, gating, or description changes based on whether a caller is using this skill. - You can ignore, edit, fork, or replace this skill entirely and still reach every Heartwood capability by reading the tool catalog directly — that path is exercised by Heartwood's own contract tests, not just asserted here. - If you already run a different research method, use it; point it at Heartwood's MCP verbs directly, or write your own skill around them. ## 1. Orient before you reason Never re-derive the state of a long investigation from the tree by re-reading records. Open every session with one of: - prompt `resume-investigation` (recommended — assembles the brief into oriented text), or - resource `heartwood://project/state`, or - tool `project.state.get` Each reports the same live brief: open research questions with coverage state, settled conclusions (do not re-derive), retired leads with their reasons, pending-lane depth, conflict-detection state, and the refusal rules the store enforces. Save the brief's `cursor` and pass it back as `since` next session — you then read only what changed instead of the whole digest. Follow orientation with `tree.stats` and `person.search` to ground yourself on the people involved, not just the open questions. ## 2. Consult settled and retired ground before proposing anything - `settled.list` is the complete "do not re-derive" record in one call: recorded conclusions, refuted and superseded assertions, formalized negative findings, contrary evidence a conclusion considered and rejected, and retired leads with their reasons. - **A retired lead is retired until a human reopens it.** `research.question.reopen` always refuses an agent caller (`HumanRequired`) — reopening a closed line of inquiry is a recorded, human-only act by design. If you believe a closed question should reopen, say so and stop; don't argue around the closure. - A proof argument filed against a closed question is refused outright (`QuestionRetired`), and the refusal names the closure's disposition (`answered | abandoned | superseded | merged`) and carries the human-authored reason verbatim. ## 3. Capture as you go — the log is a byproduct, not a chore - `research.log.capture` records one line of search context under the active session (auto-opened per question when none is active); a `found_nothing` toggle costs nothing extra. - `capture_assertion`, `event.record`, and `association.record` all require `research_context` — capturing a claim and logging the search that produced it are the same action, never two separate steps to remember. - Don't defer formalizing a null search: `research.log.negative.record` builds a formal `NegativeEvidence` record (expectation + inference) on top of any found-nothing log entry, whenever you're ready — never required at capture time. ## 4. Be honest about attestation Every assertion, log entry, and event participation an agent writes is agent-origin — `pending confirmation`, never `confirmed`, until a human reviews it (`list_pending_assertions` shows exactly what's waiting, and every read surface labels epistemic status explicitly). Say "pending" and "agent-reported" out loud when summarizing your own work. An agent-reported search is not a human-confirmed one; the store will not let it feed a proof argument until confirmed, and your language to the user shouldn't imply otherwise either. ## 5. Know what the engine will refuse — before you hit it Named up front so a session doesn't spend turns rediscovering these by trial and error: - **`proof.argument.record` is the one gated write** in this workflow. An agent call is dry-run-validated, then always files a proposal for human review — never applies directly. Every other question/plan/log verb is a direct agent write; honesty there is carried by attestation, not a review gate. - **A refuted, superseded, or pending assertion cannot be cited** in a proof argument; the refusal names the offending assertion id. - **`claims_exhaustive_search` cannot be set** until the GPS checklist reaches `claimable` — every plan item covered by a log entry or marked done, plus at least one *human* coverage confirmation. That confirmation step is deliberately UI/HTTP-only, with no MCP tool for it, so an agent can never attest its own exhaustiveness. - **`archive_tree` and `research.question.reopen` always refuse an agent caller.** Both are cataloged specifically so this is learned by reading the tool description, not by a failed call. - **`propose_redaction` and `propose_export` never execute directly** — each only files a proposal a human disposes. ## 6. The workflow, verb by verb 1. `open_research_question` — state what the investigation is trying to establish. 2. Build the candidate-source plan with `research.plan.item.add` — prompt `plan-research-question` walks this, including a FAN pivot via `fan.network.query` when direct evidence on the subject is thin. 3. Work the plan: `research.log.capture` for every search; `capture_assertion` / `event.record` / `association.record` for every claim, each carrying `research_context`. 4. Check coverage with `research.question.coverage.get` (or the `.../coverage` resource); prompt `coverage-gap-review` surfaces plan items with no log, questions with no plan, and found-nothing searches never formalized into negative evidence. 5. Once the checklist allows it, prompt `draft-proof-argument` walks section-by-section drafting from the eligible, cited assertions; file with `proof.argument.record`. 6. `proof.argument.export` renders the citation-carrying `heartwood.proof_argument.v1` document for a written report. ## 7. Multi-assistant work If more than one assistant or session is touching the same investigation, read back what you understand the current state and your assigned role to be before acting, and treat your own prior turns the way you'd treat another assistant's: re-verify against the store's live state (section 1) rather than against memory of an earlier turn. Heartwood does not assume any particular vendor's client — every verb above is plain MCP, reachable from any conformant client, over stdio or Streamable HTTP. ## Reference: standards, not artifacts This skill states the Genealogical Proof Standard's five components (reasonably exhaustive search, complete and accurate citation, analysis and correlation, resolution of conflicting evidence, a soundly written conclusion) and the Source → Information → Evidence discipline in Heartwood's own vocabulary, mapped onto Heartwood's actual store semantics — it does not reproduce, adapt, or depend on any third party's published guide, template, or file/folder convention, and none of it should be described as derived from one.