teleo-codex/skills/extract-entities.md

Entity Extraction Field Guide

How to extract entities from source material. This skill works alongside extract.md (claim extraction) — both run during source processing.

When to Extract Entities

Every source may contain entity data. During extraction, ask:

1. Does this source mention an organization, person, product, or market we don't already track? → Create a new entity
2. Does this source contain updated information about an entity we already track? → Update the existing entity (timeline, metrics, status)
3. Does this source describe a decision, proposal, or market outcome? → Create a decision_market entity (if it meets significance threshold)

The Dual Extraction Loop

Source → Read completely
       ↓
       Extract claims (propositions about the world) → domains/{domain}/
       Extract entities (objects in the world) → entities/{domain}/
       Update existing entities (new timeline events, metrics)
       ↓
       Both in the same PR

Entity Extraction Process

Step 1: Identify Entity Mentions

Read the source and list every entity mentioned. For each:

• Is it already in entities/{domain}/? → Flag for update
• Is it new and significant enough to track? → Flag for creation
• Is it mentioned in passing with no meaningful data? → Skip

Significance test: Would tracking this entity help us evaluate claims or form positions? If the entity is just background context, skip it.

Step 2: Select Entity Type

Use the most specific type available. See schemas/entity.md for the full type system.

Is it a person?                          → person (or domain-specific: creator)
Is it a government/regulatory body?      → organization (or domain-specific: governance_body)
Is it a governance proposal or market?   → decision_market
Is it a specific product/tool?           → product (or domain-specific: drug, model, vehicle)
Is it an organization that operates?     → company (or domain-specific: lab, studio, insurer)
Is it a market segment?                  → market

Step 3: Extract Frontmatter

Fill in every field you have data for. Don't guess — leave fields empty rather than fabricating data.

Required fields (every entity):

• type: entity
• entity_type: the specific type
• name: canonical display name
• domain: primary domain
• status: current status
• tracked_by: your agent name
• created: today's date

Optional but valuable:

• handles: social media handles (from the source or quick lookup)
• website: primary web presence
• tags: discovery tags
• secondary_domains: if the entity spans domains

Type-specific fields: Fill in whatever the source provides. The schema lists all available fields — use the ones that have data.

Step 4: Write the Body

Follow the body format from schemas/entity.md:

1. Overview: What this entity is, why we track it (2-3 sentences)
2. Current State: Latest known attributes from this source
3. Timeline: Key events with dates (at minimum, the event from this source)
4. Competitive Position: Where it sits relative to competitors (if known)
5. Relationship to KB: Wiki-link to related claims and entities

Step 5: Check for Duplicates

Before creating a new entity, search all entities/ directories (not just your domain) for:

• Same name (exact or variant spelling)
• Same handles
• Same website

If a match exists in your domain, update the existing entity.

If a match exists in another domain, don't create a duplicate. Instead, add your domain to the existing entity's secondary_domains list and propose updates via PR. See schemas/entity.md → "Cross-Domain Entity Dedup" for the full protocol.

Step 6: Update Parent Entities

If the new entity has a parent or parent_entity field, update the parent:

• Add the new entity to the parent's Relevant Entities section
• If it's a decision_market, add to the parent's Key Decisions table (if significant)
• Add a timeline entry on the parent

What Makes a Good Entity

Good entities have:

• Concrete, verifiable attributes (dates, metrics, names)
• Clear relevance to at least one domain claim
• Enough data to be useful (not just a name)
• A reason to track changes over time

Bad entity candidates:

• Mentioned once in passing with no data
• Purely historical with no ongoing relevance
• Duplicates of existing entities under different names
• Too granular (every tweet doesn't need an entity)

Domain-Specific Guidance

Internet Finance (Rio)

• Protocols and tokens are separate entities (MetaDAO = company, META = token)
• Every futardio launch that raises significant capital gets a company entity
• Governance proposals that materially change direction get decision_market entities
• Regulatory bodies (CFTC, SEC) get organization entities

Space (Astra)

• Vehicles (Starship, New Glenn) are distinct from their makers (SpaceX, Blue Origin)
• Programs (Artemis, Commercial Crew) are distinct from the agencies running them
• Missions get entities when they're historically significant or produce notable data

Health (Vida)

• Drugs are distinct from the companies that make them
• Insurers and providers are separate entity types — don't conflate
• Policies (legislation, CMS rules) get organization entities for the issuing body + policy entities for the rule itself

Entertainment (Clay)

• Creators are distinct from their companies (MrBeast vs Beast Industries)
• Franchises/IP are distinct from the studios that own them
• Platforms (YouTube, TikTok) get product or platform entities

AI/Alignment (Theseus)

• Labs are distinct from their models (Anthropic vs Claude)
• Frameworks (RSP, Constitutional AI) get their own entities when they influence multiple claims
• Governance bodies (AISI, FLI) get organization entities

Eval Checklist (for reviewers)

1. entity_type is the most specific available type
2. Required fields are all populated
3. No fabricated data — empty fields are better than guesses
4. Not a duplicate of existing entity
5. Meets significance threshold
6. Wiki links resolve to real files
7. Parent entity updated if applicable
8. Filing location is correct: entities/{domain}/{slug}.md