Ref Ingest

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).

State Dependencies

The automation split (load-bearing)

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.