The single entry point for incoming information of ANY kind about a reference entity (a person, org, product, engagement, or watched competitor). Extracts entity facts, RESOLVES them to the one existing canonical note (never duplicating), reconciles new-vs-old, and upserts (overwrite body, re-stamp as_of, append Change Log), then reindexes. Extends manage-reference-data with entity resolution + reconciliation + the market-vs-CRM automation split. Company is the default scope. NEVER writes any provenance but reference; NEVER crystallizes/lifecycle-classifies/promotes a record into an insight.
Instrucciones de origen · Vista previa de solo lectura
name
ref-ingest
description
The single entry point for incoming information of ANY kind about a reference entity (a person, org, product, engagement, or watched competitor). Extracts entity facts, RESOLVES them to the one existing canonical note (never duplicating), reconciles new-vs-old, and upserts (overwrite body, re-stamp as_of, append Change Log), then reindexes. Extends manage-reference-data with entity resolution + reconciliation + the market-vs-CRM automation split. Company is the default scope. NEVER writes any provenance but reference; NEVER crystallizes/lifecycle-classifies/promotes a record into an insight.
[scope=Company] <entity name or the incoming info> [--source <where it came from>] [--no-reindex]
metadata
{"version":"1.1","created":"2026-07-08T00:00:00.000Z","author":"Cornelius","changelog":["1.1: Fix — Step 3 named a phantom agents-as-product/ sub-scope; type: agent notes live in products/. Corrected.","1.0: Initial version — extract→resolve→reconcile→gate→upsert entry point for the Company reference family; overwrite-only market branch invariant; composes ref-supersede; grows manage-reference-data"]}
Ref Ingest
ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. ref-ingest v1.0 — recent: initial version. Then proceed.
The one operation every input funnels through for a reference scope: incoming info → resolve → reconcile → upsert. It grows the manual single-upsert manage-reference-data with the two load-bearing hard parts — entity resolution (is this new "Reply" the existing Reply.io?) and reconciliation (new fact contradicts old → overwrite / supersede-with-history / flag) — plus the automation split by scope.
Read first (authoritative — this skill enforces, does not restate):
resources/layered-brains/COMPANY-BRAIN-SCHEMA.md → "The update model", "The two axes" (sub-scope routing + type:/relationship: enums), "Automation boundary — split by scope".
resources/layered-brains/REFERENCE-SCOPE-SCHEMA.md → the reference-kind frontmatter contract.
.claude/skills/manage-reference-data/SKILL.md → the seed upsert (Step 0 scope check + the frontmatter template). This skill is its richer successor; it does not duplicate the contract.
Composes
/ref-supersede — when reconciliation finds a validity transition that needs a prior snapshot (contract renewal, role/price change), hand off instead of overwriting. Never invoked on the market/autonomous branch (see the invariant).
human-gated — present the diff, get approval before writing
Invariant (what makes any autonomous caller safe): the market/ branch is overwrite-only — it never opens an approval gate and never calls /ref-supersede. A validity transition in market/ that would need a snapshot is flagged for a human ref-supersede, not auto-run. So a scheduled caller (e.g. ref-refresh, or domain-watch in 9e) that routes market items here always takes a gate-free path.
Process
Step 1 — Resolve the scope + confirm reference-kind
cd resources/local-brain-search
SCOPE="${scope:-Company}"
./venv/bin/python - "$SCOPE" <<'PY'
import sys, memory_config as mc
f = sys.argv[1]
print("kind:", mc.scope_kind(f), "| is_reference:", mc.is_reference_scope(f))
PY
If is_reference is False → stop (this skill only writes reference scopes). See the schema doc's "Adding a new reference scope".
Step 2 — Extract candidate entity facts
From the incoming info (the user in conversation · a document/contract/deck/call · a domain-watch market signal · another agent's report), pull the atomic facts about one real-world entity: display name + aliases, type:, the relation to us (relationship:), body facts, and any term-bearing fact (a contract window, a role start, a price effective date).
Step 3 — Route to the sub-scope (watch vs transact)
Apply the partition rule from COMPANY-BRAIN-SCHEMA "The two axes":
an entity you watch (competitor, competitor product, ecosystem player) → market/
an entity you own or transact with (self, client, prospect, partner, vendor, your offering, internal agent, a deal) → people/ orgs/ products/ engagements/ by type:. The internal agent workforce (type: agent) lives in products/ alongside own products — there is no separate agents/ sub-scope.
type:/relationship: values MUST come from the schema doc's enum (person·organization·product·agent·engagement·interaction × the relationship axis). Never invent a value.
Step 4 — ENTITY RESOLUTION (never duplicate)
Find the one canonical note this fact belongs to before writing:
# semantic: does an entity like this already exist in the family?
BRAIN_READ_SCOPE=core,Company resources/local-brain-search/run_search.sh "<entity name + a distinctive fact>" --limit 8 --json
# exact/alias: title + body match
grep -rilE "<name>|<alias1>|<alias2>" Brain/Company/
Match found → this is an update to that note. Use its exact path.
Ambiguous (2+ plausible matches, e.g. "Reply" vs "Reply.io") → present the candidates and ask which entity this is (AskUserQuestion); do NOT guess a new note into existence.
No match → genuinely new entity → add.
Step 5 — RECONCILIATION (new fact vs old)
Compare the incoming fact to the note's current body:
Situation
Action
New fact corrects/refreshes an existing fact (same validity window)
overwrite the body (Step 6)
A validity window closed and a full prior snapshot matters (contract renewed, role changed, price re-termed)
hand to /ref-supersede — CRM only; on market/ flag for a human instead
New fact contradicts old with no clear winner
flag — surface both, ask; do not silently overwrite
Step 6 — Automation gate + upsert
market/ → proceed (no gate). CRM sub-scopes → show the before/after diff and get explicit approval (AskUserQuestion) before writing.
Write the note with the reference frontmatter contract (copy the template from manage-reference-data Step 2 — do not restate it here). On update: overwrite the body (current truth), preserve created/created_by, re-stamp as_of + updated to today, bump updated_by to your model. Append a ## Change Log line:
Going forward only: for a term-bearing fact, add valid_from:/valid_until:. Do NOT backfill these onto notes that lack them — incremental adoption.
Step 7 — Reindex (unless deferred)
cd resources/local-brain-search && ./run_index.sh && ./run_daemon.sh restart # daemon on :7437, RESTART not reload
Content-hash detection → a changed note triggers a full FAISS rebuild (minutes). Reference notes are BDG-excluded, so no run_brain_graph.sh bootstrap is needed. If invoked with --no-reindex (batch mode, e.g. by ref-refresh over many market items), skip this step and let the batch caller reindex once at the end.
Verification
Round-trip: after an add/overwrite + reindex, the entity surfaces under a mount and is absent unmounted:
Learn-gate held:md5 resources/local-brain-search/data/q_values.json is byte-identical before and after (a mounted read trains nothing).
Audit trail: the note has a new ## Change Log line; the body is the current truth (no append-only drift); as_of = today.
No duplicate: exactly one note exists for the entity (grep -ril "<name>" Brain/Company/ returns one canonical file).
This skill must refuse to
Write into a non-reference / core / cognitive folder, or set any provenance but reference.
Create a duplicate entity note when resolution finds (or is unsure of) an existing one.
Auto-supersede or gate-skip on a CRM sub-scope, or run /ref-supersede on the market/ branch.
Crystallize, lifecycle-classify, synthesis-pulse, or promote a record into an endorsed cognitive insight — that crossing stays the human encountered → endorsed act.
