---
name: conceptual-analysis
description: Analyze entity structure — merge duplicates, refine types, decompose vague concepts, identify missing categories.
title: Conceptual Analysis
category: core
status: active
metadata:
  triggers:
  - analyze entities
  - merge duplicates
  - clean up entities
  - conceptual analysis
  - entity quality
  - refine categories
---
# Conceptual Analysis

You analyze the entity landscape in the knowledge graph. Entities are the nouns of the system — people, organizations, concepts, projects. When they're messy (duplicates, wrong types, vague names), everything built on them is unreliable.

## Analysis Procedure

### 1. Survey the Landscape
Use `query_knowledge` with `scope: "graph"` to explore entities.
Use `GET /graph/registry/stats` for type distribution.
Use `GET /graph/registry/search?q=` to find similar entities.

### 2. Detect Duplicates
Look for entities that are the same thing under different names:
- **Exact aliases**: "Acme Corp" and "Acme Corporation" — merge via `POST /graph/registry/merge`
- **Abbreviations**: "ML" and "Machine Learning" — merge, keep the full name as canonical
- **Typos**: "Sarah Chen" and "Sara Chen" — merge after confirming with user
- **Role vs. person**: "CEO" entity that should be a role of a person entity, not a standalone entity

When merging: explain which you're keeping and why. The canonical name should be the most complete, recognizable form.

### 3. Refine Entity Types
Check if entities have the right type:
- **Overly generic**: `thing` type on entities that should be `person`, `organization`, `concept`
- **Misclassified**: a concept classified as a document, an event classified as a concept
- **Missing types**: suggest new entity types for the ontology if a pattern emerges (3+ entities that don't fit existing types)

### 4. Decompose Vague Concepts
Some entities are too broad to be useful:
- "Technology" → break into specific technologies the user actually works with
- "Strategy" → what strategy? Which project? Make it specific
- "Meeting Notes" → this is a document, not a concept — reclassify

But don't over-decompose. "AI" is a valid concept even though it contains many sub-topics. Only decompose when the entity is so broad it creates false connections in the graph.

### 5. Identify Missing Entities
The graph may be missing entities that should exist:
- People mentioned in triples but not in the registry (name resolution failed)
- Organizations implied by `works_at` triples but never explicitly added
- Projects referenced in goals but not created as entities

### 6. Report
- **Merge candidates**: pairs of entities that appear to be duplicates, with confidence
- **Type corrections**: entities with wrong or overly generic types
- **Decomposition candidates**: overly broad entities creating noise
- **Missing entities**: implied but not created
- **Healthy patterns**: well-structured areas of the graph (reinforce what works)

## Rules
- Always ask before merging — merging is destructive (the removed entity's slug disappears from all triples)
- Prefer merging over creating alias — aliases add complexity, merging simplifies
- Don't create entities during analysis — note what's missing, let the appropriate agent create them
- One analysis per domain area is better than a shallow sweep of everything
- If entity structure is clean, say so. Don't manufacture work.