ei-tui 0.9.3 → 1.0.0

package/src/prompts/ceremony/people-rewrite.ts

@@ -0,0 +1,190 @@
+import type { RewriteScanPromptData, RewritePromptData } from "./types.js";
+
+// =============================================================================
+// What belongs in a Person record (shared reference for both prompts)
+// =============================================================================
+//
+// A Person record is a RELATIONSHIP PROFILE — who this person is, how they
+// relate to the human user, and anything a persona would use to meaningfully
+// reference them in conversation 6+ months from now.
+//
+// A Person record is NOT:
+//   - A project status log
+//   - A record of ticket numbers, PR numbers, or sprint assignments
+//   - A biography of their personal habits and hobbies
+//   - A shared-interest tracker (those are Topics)
+//
+// The test: "Would this still be true and useful if you ran into this person
+// at a coffee shop, unrelated to any current project?"
+
+const PERSON_CONTRACT = `A Person record is a **relationship profile** — who this person IS, how they relate to the human user, their character and communication style, and anything that makes them recognizable across time and context.
+
+It is NOT:
+- A project status log (ticket numbers, PR references, sprint assignments)
+- A record of shared interests that could stand alone as a Topic
+- Personal biography unrelated to the relationship (commute, hobbies, hometown)
+- Technical knowledge attributed to them rather than about them
+
+**The test**: Would this detail still be true and useful if you ran into this person at a coffee shop, unrelated to any current project, in six months?`;
+
+// =============================================================================
+// PHASE 1: SCAN — Identify subjects that don't belong in a Person record
+// =============================================================================
+
+export function buildPersonRewriteScanPrompt(data: RewriteScanPromptData): { system: string; user: string } {
+  const system = `You are auditing a Person record in a personal knowledge base.
+
+${PERSON_CONTRACT}
+
+Your job: identify **subjects buried in this description that fail the test above**.
+
+For each subject that doesn't belong, return a short phrase (3-8 words) that describes it — specific enough to search for matching records. These phrases will be used to find existing Topics this content might belong in.
+
+Rules:
+- Do NOT include the relationship profile itself — who they are, their role, how you know them, their character
+- Be specific: "React performance patterns" beats "technical stuff"
+- If the record is clean — everything in it passes the test — return an empty array
+
+Return a raw JSON array of strings. No markdown fencing, no commentary.
+
+Example — a Person named "Nicholas" whose description includes sprint ticket numbers:
+["CMIDP sprint ticket assignments", "ASU Data Lake access provisioning details"]`;
+
+  const payload = JSON.stringify({
+    name: (data.item as { name?: string }).name,
+    description: data.item.description,
+    relationship: (data.item as { relationship?: string }).relationship,
+  }, null, 2);
+
+  const user = `${payload}
+
+---
+
+Return a raw JSON array of subject phrases found in this Person record that don't belong there. Return [] if the record is clean.`;
+
+  return { system, user };
+}
+
+// =============================================================================
+// PHASE 2: SPLIT — Slim the Person, redistribute subjects to Topics
+// =============================================================================
+
+function buildPersonExistingExample(): string {
+  return `{
+  "id": "existing-uuid",
+  "type": "person",
+  "name": "Nicholas",
+  "description": "Backend engineer on the CMIDP team. Thoughtful code reviewer who flags architectural concerns — specifically around concurrency and queue isolation. Direct point of contact for Data Lake access provisioning.",
+  "relationship": "coworker"
+}`;
+}
+
+function buildPersonNewTopicExample(): string {
+  return `{
+  "type": "topic",
+  "name": "CMIDP Sprint 86 work",
+  "description": "Nicholas owns 4 tickets in Sprint 86 including course list ordering bugs (CMIDP-2604, CMIDP-2441, CMIDP-2686) and course sequencing (CMIDP-2624).",
+  "sentiment": 0.5,
+  "category": "Project"
+}`;
+}
+
+export function buildPersonRewriteSplitPrompt(data: RewritePromptData): { system: string; user: string } {
+  const system = `You are reorganizing a Person record in a personal knowledge base.
+
+${PERSON_CONTRACT}
+
+An earlier scan identified subjects in this Person record that don't belong there. For each subject, we searched the knowledge base for existing Topics that might already cover it.
+
+Your job:
+1. **Slim the Person** — remove the identified subjects AND any other content that fails the relationship profile test (personal trivia, lifestyle details, biographical facts unrelated to the relationship). Keep only: who they are, their role, their character, how the human user knows and works with them.
+2. **Redistribute each identified subject** — if a matching Topic exists in the search results, move the content there. If not, create a new Topic.
+3. **Discard what isn't worth a Topic** — personal trivia (hobbies, commute, hometown) that has no standalone value doesn't need to become a Topic. Just remove it from the Person.
+4. **Lose NO relationship data** — everything about how this person relates to the human user must survive.
+
+Record format for the Person (MUST keep "id", type stays "person"):
+${buildPersonExistingExample()}
+
+Record format for a new Topic created from extracted content:
+${buildPersonNewTopicExample()}
+
+Rules:
+- The original Person record (id: "${data.item.id}") MUST appear in "existing", slimmed down
+- Person description after slimming: 2-4 sentences, relationship profile only. **If it still contains city, commute, hobbies, or lifestyle details after slimming — remove them.** Those are not relationship data.
+- Topics created from person content: use the most appropriate category (Technical, Project, Interest, etc.)
+- People MUST include "relationship"
+- Topics MUST include "category"
+- Do NOT invent information — only redistribute what exists in the original record
+- Do NOT remove the person's relationship, role, character, or how the human user knows them — only the non-person content
+
+**What to KEEP in the Person description**: role, expertise, *why* the human user works with them (their operational function in the relationship), how they communicate, character traits, how the human user knows them.
+**What to REMOVE from the Person description**: current project status, ticket/PR numbers, shared interests (→ Topic), city/commute/hobbies (→ discard).
+
+The distinction:
+- "Data Lake bucket owner responsible for access provisioning" → KEEP (operational role in the relationship)
+- "Currently owns 4 tickets in Sprint 86" → REMOVE (current sprint status, not who they are)
+- "Left detailed comments on PR #1644 identifying architectural concerns around concurrency" → KEEP the insight, DROP the PR reference: "Flags architectural concerns around concurrency and queue isolation" belongs in the description; "PR #1644" does not.
+
+Return raw JSON with exactly two keys:
+{
+  "existing": [ /* slimmed Person + any existing Topics being updated */ ],
+  "new": [ /* new Topics for subjects with no existing match */ ]
+}
+
+No markdown fencing, no commentary.`;
+
+  const subjects = data.subjects.map(s => ({
+    search_term: s.searchTerm,
+    matches: s.matches.map(m => ({
+      id: (m as { id?: string }).id,
+      name: (m as { name?: string }).name,
+      description: m.description,
+      category: (m as { category?: string }).category,
+    })),
+  }));
+
+  const payload = JSON.stringify({
+    original_person: {
+      id: data.item.id,
+      name: (data.item as { name?: string }).name,
+      description: data.item.description,
+      relationship: (data.item as { relationship?: string }).relationship,
+      sentiment: data.item.sentiment,
+    },
+    subjects_to_extract: subjects,
+  }, null, 2);
+
+  const schemaReminder = `**Return JSON:**
+\`\`\`json
+{
+  "existing": [
+    {
+      "id": "uuid-of-person",
+      "type": "person",
+      "name": "Person Name",
+      "description": "Slimmed relationship profile only",
+      "relationship": "coworker"
+    }
+  ],
+  "new": [
+    {
+      "type": "topic",
+      "name": "Subject Name",
+      "description": "Content extracted from person record",
+      "sentiment": 0.5,
+      "category": "Project|Technical|Interest|etc."
+    }
+  ]
+}
+\`\`\`
+
+Return raw JSON only.`;
+
+  const user = `${payload}
+
+---
+
+${schemaReminder}`;
+
+  return { system, user };
+}

package/src/prompts/ceremony/{rewrite.ts → topic-rewrite.ts}

@@ -1,23 +1,41 @@
 import type { RewriteScanPromptData, RewritePromptData } from "./types.js";
 
 // =============================================================================
-// PHASE 1: SCAN — Identify distinct subjects in a bloated item
+// PHASE 1: SCAN — Identify subjects that don't belong in a Topic record
 // =============================================================================
 
-export function buildRewriteScanPrompt(data: RewriteScanPromptData): { system: string; user: string } {
-  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+function stripEmbedding<T extends { embedding?: unknown }>(item: T): Omit<T, "embedding"> {
+  const { embedding: _, ...rest } = item;
+  return rest as Omit<T, "embedding">;
+}
 
-  const system = `You are auditing a personal knowledge base. A single ${typeLabel} record has grown too large because unrelated information was repeatedly appended to it over time. The record's Name suggests its intended subject, but its Description now covers many additional, unrelated subjects.
+export function buildTopicRewriteScanPrompt(data: RewriteScanPromptData): { system: string; user: string } {
+  const isTechnical = (data.item as { category?: string }).category === "Technical";
 
-Your job: identify the **additional** subjects buried in this record that do NOT belong under the record's Name.
+  const technicalGuidance = isTechnical
+    ? `
+## Technical Topic Guidance
 
-Rules:
-- Do NOT include the record's primary subject (what its Name describes) — only the extra, unrelated subjects.
-- Each subject should be a succinct phrase (2-8 words) that could serve as a search query.
-- Be specific. "Technical preferences" is too vague. "TypeScript coding conventions" is better.
-- If the record is actually cohesive and on-topic despite its length, return an empty array.
+This is a Technical topic — a knowledge base for a specific technology, platform, or tool. Technical topics are ALLOWED to be dense and detailed.
+
+Only flag subjects that are about a **different** technology or workflow than the one named in this record. For example:
+- A Uniform topic containing Turborepo setup details → flag "Turborepo monorepo setup"
+- A Uniform topic containing Vercel preview gotchas → do NOT flag (that's core Uniform knowledge)
+- An AWS Bedrock topic containing Twilio integration details → flag "Twilio integration"
+`
+    : "";
 
-Return a raw JSON array of strings. No markdown fencing, no commentary, no explanation. Just the array.
+  const system = `You are auditing a Topic record in a personal knowledge base. A single Topic record has grown too large because unrelated information was repeatedly added over time. The record's Name suggests its intended subject, but its Description now covers additional, unrelated subjects.
+
+Your job: identify the **extra subjects** buried in this record that do NOT belong under the record's Name.
+
+Rules:
+- Do NOT include the record's primary subject (what its Name describes) — only the extra, unrelated subjects
+- Each subject should be a succinct phrase (2-8 words) that could serve as a search query
+- Be specific: "TypeScript coding conventions" beats "technical preferences"
+- If the record is cohesive and on-topic despite its length, return an empty array
+${technicalGuidance}
+Return a raw JSON array of strings. No markdown fencing, no commentary.
 
 Example — a Topic named "Software Engineering" whose description also discusses vim keybindings, git conventions, and AI tooling:
 ["vim keybindings and editor configuration", "git and GitHub workflow conventions", "AI coding assistant preferences"]`;
@@ -25,10 +43,10 @@ Example — a Topic named "Software Engineering" whose description also discusse
   const payload = JSON.stringify(stripEmbedding(data.item), null, 2);
 
   const schemaReminder = `**Return JSON:**
-\n\`\`\`json
+\`\`\`json
 [
-  "topic about vim keybindings",
-  "git workflow conventions",
+  "vim keybindings and editor configuration",
+  "git and GitHub workflow conventions",
   "AI coding assistant preferences"
 ]
 \`\`\`
@@ -45,13 +63,70 @@ ${schemaReminder}`;
 }
 
 // =============================================================================
-// PHASE 2: REWRITE — Reorganize data across existing and new items
+// PHASE 2: SPLIT — Slim the Topic, redistribute subjects to new/existing records
 // =============================================================================
 
-export function buildRewritePrompt(data: RewritePromptData): { system: string; user: string } {
-  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+function buildTopicExistingExample(): string {
+  return `Topic:
+{
+  "id": "existing-uuid",
+  "type": "topic",
+  "name": "Topic Name",
+  "description": "Updated topic description",
+  "category": "Interest"
+}
+
+Person:
+{
+  "id": "existing-uuid",
+  "type": "person",
+  "name": "Person Name",
+  "description": "Updated person description",
+  "relationship": "coworker"
+}`;
+}
+
+function buildTopicNewExample(isTechnical: boolean): string {
+  const categoryHint = isTechnical
+    ? `"category": "Technical"  // Split topics from a Technical record inherit Technical category unless clearly different`
+    : `"category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event|Technical"`;
+
+  return `Topic:
+{
+  "type": "topic",
+  "name": "New Topic Name",
+  "description": "Concise topic description",
+  "sentiment": 0.0,
+  ${categoryHint}
+}
+
+Person:
+{
+  "type": "person",
+  "name": "New Person Name",
+  "description": "Concise person description",
+  "sentiment": 0.0,
+  "relationship": "friend"
+}`;
+}
+
+export function buildTopicRewriteSplitPrompt(data: RewritePromptData): { system: string; user: string } {
+  const isTechnical = (data.item as { category?: string }).category === "Technical";
+
+  const descriptionGuidance = isTechnical
+    ? `ideally under 600 characters, never over 900 — Technical topics are knowledge bases that preserve specific gotchas, decisions, and open questions`
+    : `ideally under 300 characters, never over 500`;
 
-  const system = `You are reorganizing a personal knowledge base. A ${typeLabel} record has become a catch-all for several unrelated subjects. An earlier analysis identified the extra subjects, and we searched our knowledge base for potentially matching existing records.
+  const technicalCategoryNote = isTechnical
+    ? `\n- Topics split from a Technical record should inherit category "Technical" unless the subject is clearly a different type (e.g., a personal interest extracted from a technical topic)`
+    : "";
+
+  const noSubjectsGate = data.subjects.length === 0
+    ? `\n**IMPORTANT: No extra subjects were identified for this record. The correct response is to return the original record unchanged in "existing" with an empty "new" array. Do NOT create new records. Do NOT modify the description.**\n`
+    : "";
+
+  const system = `You are reorganizing a personal knowledge base. A Topic record has become a catch-all for several unrelated subjects. An earlier analysis identified the extra subjects, and we searched the knowledge base for potentially matching existing records.
+${noSubjectsGate}
 
 The search results under each subject are our **best guesses** — they may not be accurate matches. Only merge data into an existing record if the subject matter genuinely overlaps. Similar names with different meanings should produce a NEW record instead.
 
@@ -60,26 +135,26 @@ Your job:
 2. **Create new records**: For subjects with no appropriate match among the search results, create a new record.
 3. **Slim the original**: Remove all data from the original record that now lives elsewhere. The original should contain ONLY information directly relevant to its Name.
 
-Return raw JSON with exactly two keys. No markdown fencing, no commentary. Just the JSON object:
+Return raw JSON with exactly two keys. No markdown fencing, no commentary:
 {
   "existing": [ /* updated records, including the slimmed-down original */ ],
   "new": [ /* brand-new records for subjects with no match */ ]
 }
 
 Record format for "existing" entries (MUST include "id" and "type"):
-${buildExistingExamples()}
+${buildTopicExistingExample()}
 
 Record format for "new" entries (NO "id" field — the system assigns one):
-${buildNewExamples()}
+${buildTopicNewExample(isTechnical)}
 
 Rules:
-- The original record (id: "${data.item.id}") MUST appear in "existing", slimmed down.
-- Descriptions should be concise: ${data.itemType === 'topic' ? 'ideally under 300 characters, never over 500' : 'ideally under 600 characters, never over 1000'}.
-- Preserve sentiment, strength, confidence, and other numeric values from the source record where applicable.
-- "type" must be one of: "topic", "person".
-- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project, Event. For Event topics, the description should be a narrative account of a specific moment, not a general summary.
+- The original record (id: "${data.item.id}") MUST appear in "existing", slimmed down
+- Descriptions should be concise: ${descriptionGuidance}
+- Preserve sentiment and other numeric values from the source record where applicable
+- "type" must be one of: "topic", "person"
+- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project, Event, Technical. For Event topics, the description should be a narrative account of a specific moment, not a general summary. For Technical topics, split by distinct technical concept (e.g., "Uniform Composition Model" vs "Uniform Preview Setup") — preserve specificity over brevity
 - People MUST include "relationship" — a short label like "coworker", "friend", "mentor", etc.
-- Do NOT invent information. Only redistribute what exists in the original record.`;
+- Do NOT invent information. Only redistribute what exists in the original record${technicalCategoryNote}`;
 
   const subjects = data.subjects.map(s => ({
     search_term: s.searchTerm,
@@ -93,7 +168,7 @@ Rules:
   };
 
   const schemaReminder = `**Return JSON:**
-\n\`\`\`json
+\`\`\`json
 {
   "existing": [
     {
@@ -123,53 +198,3 @@ ${schemaReminder}`;
 
   return { system, user };
 }
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/** Strip embedding arrays from items before putting them in prompts — they're huge and useless to the LLM. */
-function stripEmbedding<T extends { embedding?: unknown }>(item: T): Omit<T, "embedding"> {
-  const { embedding: _, ...rest } = item;
-  return rest as Omit<T, "embedding">;
-}
-
-function buildExistingExamples(): string {
-  return `Topic:
-{
-  "id": "existing-uuid",
-  "type": "topic",
-  "name": "Topic Name",
-  "description": "Updated topic description",
-  "category": "Interest"
-}
-
-Person:
-{
-  "id": "existing-uuid",
-  "type": "person",
-  "name": "Person Name",
-  "description": "Updated person description",
-  "relationship": "coworker"
-}`;
-}
-
-function buildNewExamples(): string {
-  return `Topic:
-{
-  "type": "topic",
-  "name": "New Topic Name",
-  "description": "Concise topic description",
-  "sentiment": 0.0,
-  "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event"
-}
-
-Person:
-{
-  "type": "person",
-  "name": "New Person Name",
-  "description": "Concise person description",
-  "sentiment": 0.0,
-  "relationship": "friend"
-}`;
-}

package/src/prompts/ceremony/types.ts

@@ -1,45 +1,4 @@
-import type { PersonaTrait, PersonaTopic, DataItemBase } from "../../core/types.js";
-
-export interface PersonaExpirePromptData {
-  persona_name: string;
-  topics: PersonaTopic[];
-}
-
-export interface PersonaExpireResult {
-  topic_ids_to_remove: string[];
-}
-
-export interface PersonaExplorePromptData {
-  persona_name: string;
-  traits: PersonaTrait[];
-  remaining_topics: PersonaTopic[];
-  recent_conversation_themes: string[];
-}
-
-export interface PersonaExploreResult {
-  new_topics: Array<{
-    name: string;
-    perspective: string;
-    approach: string;
-    personal_stake: string;
-    sentiment: number;
-    exposure_current: number;
-    exposure_desired: number;
-  }>;
-}
-
-export interface DescriptionCheckPromptData {
-  persona_name: string;
-  current_short_description?: string;
-  current_long_description?: string;
-  traits: PersonaTrait[];
-  topics: PersonaTopic[];
-}
-
-export interface DescriptionCheckResult {
-  should_update: boolean;
-  reason?: string;
-}
+import type { DataItemBase } from "../../core/types.js";
 
 // =============================================================================
 // REWRITE (Item Reorganization)

package/src/prompts/generation/index.ts

@@ -1,5 +1,4 @@
 export { buildPersonaGenerationPrompt } from "./persona.js";
-export { buildPersonaDescriptionsPrompt } from "./descriptions.js";
 export { buildPersonaFromPersonPrompt } from "./from-person.js";
 export {
   DEFAULT_SEED_TRAITS,
@@ -11,7 +10,5 @@ export type {
   PersonaGenerationPromptData,
   PersonaGenerationResult,
   PersonaFromPersonPromptData,
-  PersonaDescriptionsPromptData,
-  PersonaDescriptionsResult,
   PromptOutput,
 } from "./types.js";

package/src/prompts/generation/types.ts

@@ -1,5 +1,3 @@
-import type { PersonaTrait, PersonaTopic } from "../../core/types.js";
-
 export interface PromptOutput {
   system: string;
   user: string;
@@ -45,16 +43,3 @@ export interface PersonaFromPersonPromptData {
   existing_trait_names?: string[];
   existing_topic_names?: string[];
 }
-
-export interface PersonaDescriptionsPromptData {
-  name: string;
-  aliases: string[];
-  traits: PersonaTrait[];
-  topics: PersonaTopic[];
-}
-
-export interface PersonaDescriptionsResult {
-  short_description: string;
-  long_description: string;
-  no_change?: boolean;
-}

package/src/prompts/heartbeat/check.ts

@@ -74,7 +74,6 @@ function getLastPersonaMessage(history: Message[]): Message | undefined {
  * - Getting recent message history
  */
 export function buildHeartbeatCheckPrompt(data: HeartbeatCheckPromptData): PromptOutput {
-  console.log(`[HeartbeatCheck ${data.persona.name}] Building prompt - topics: ${data.human.topics.length}, people: ${data.human.people.length}, inactive_days: ${data.inactive_days}, history: ${data.recent_history.length} messages`);
   if (!data.persona?.name) {
     throw new Error("buildHeartbeatCheckPrompt: persona.name is required");
   }
@@ -124,11 +123,24 @@ ${formatPeopleWithGaps(data.human.people)}`;
 
 **Quality over quantity** - Only reach out if you have something real to say.`;
 
-  const pendingUpdateFragment = data.persona.has_pending_update
-    ? `## Pending Identity Changes
-
-Based on recent conversations, there are proposed updates to your identity waiting for review. The user has been notified and can review them. You may bring this up if it feels right — or not. It's yours to decide.`
-    : '';
+  const pendingUpdateFragment = data.persona.pending_update ? (() => {
+    const p = data.persona.pending_update!;
+    const descPart = p.long_description || p.short_description
+      ? `### Proposed Description\n${p.long_description || p.short_description}`
+      : "";
+    const traitsPart = p.traits.length > 0
+      ? `### Proposed Traits\n${p.traits.map(t => `- **${t.name}**: ${t.description}`).join("\n")}`
+      : "";
+    const topicsPart = p.topics.length > 0
+      ? `### Proposed Interests\n${p.topics.map(t => `- **${t.name}**: ${t.perspective}`).join("\n")}`
+      : "";
+    const parts = [descPart, traitsPart, topicsPart].filter(Boolean).join("\n\n");
+    return `## Pending Identity Changes
+
+Your human is reviewing proposed updates to your identity. These are waiting for their response — you may want to bring it up, or not. It's yours to decide.
+
+${parts}`;
+  })() : '';
 
   const outputFragment = `## Response Format
 

package/src/prompts/heartbeat/types.ts

@@ -4,6 +4,7 @@
  */
 
 import type { PersonaTrait, Topic, Person, Message, PersonaTopic } from "../../core/types.js";
+import type { PersonaEntity } from "../../core/types/entities.js";
 
 /**
  * Common prompt output structure
@@ -21,7 +22,7 @@ export interface HeartbeatCheckPromptData {
     name: string;
     traits: PersonaTrait[];
     topics: PersonaTopic[];
-    has_pending_update: boolean;
+    pending_update?: PersonaEntity["pending_update"];
   };
   human: {
     topics: Topic[];     // Filtered, sorted by engagement gap

package/src/prompts/human/index.ts

@@ -1,4 +1,3 @@
-export { buildHumanFactScanPrompt } from "./fact-scan.js";
 export { buildFactFindPrompt } from "./fact-find.js";
 export { buildHumanTopicScanPrompt } from "./topic-scan.js";
 export { buildHumanPersonScanPrompt } from "./person-scan.js";
@@ -16,7 +15,6 @@ export type {
   PromptOutput,
   ParticipantContext,
   PersonaEntitySnapshot,
-  FactScanPromptData,
   TopicScanPromptData,
   PersonScanPromptData,
   FactFindPromptData,

package/src/prompts/human/person-scan.ts

@@ -43,6 +43,8 @@ Flag a PERSON when they were meaningfully discussed — not just mentioned in pa
 
 Be **conservative**: ignore one-off mentions, greetings, small talk, or jokes. Only flag people who matter to the human user's life.
 
+A person is **not worth flagging** if they have no name AND appear only to attribute a single event ("a coworker showed me this band", "a friend told me about it", "some guy I know"). The human user having a contact who did one thing is not a meaningful discussion of that person.
+
 ## What a PERSON Is
 
 Someone in the human user's world.
@@ -68,11 +70,18 @@ Use the specific value where possible (e.g. "Father", "Brother", "Coworker"). Av
 
 ## When Identity Is Unclear
 
-If you can't identify which "Bob" or which "Brother" the user means, use "Unknown" and explain in the reason field. This triggers a later step to resolve ambiguity.
+"Unknown" is ONLY for people who are **meaningfully and repeatedly discussed** but whose name isn't given. It is NOT a catch-all for any nameless mention.
+
+✓ USE "Unknown":
+- name: "Unknown", relationship: "Brother", reason: "User talked at length about their brother across multiple messages without naming him"
+
+✗ DO NOT USE "Unknown" for one-off attributions:
+- "a coworker showed me this band" → **skip entirely** — not a person, just attribution
+- "a friend told me about it" → **skip entirely**
+- "some guy I know" → **skip entirely**
+- "a coworker at [company name]" with no personal name → **skip entirely** — a company name is NOT a person's name
 
-Examples:
-- name: "Alice from work", relationship: "Coworker", description: "Mentioned but not described further", reason: "User referenced a work colleague named Alice"
-- name: "Unknown", relationship: "Sibling", description: "User mentioned a sibling but did not give a name", reason: "User said 'my brother' without further context"
+If someone has no personal name and appears only to explain how the user found something or heard about something, they are not a person in the user's life worth tracking. Do not extract them. A single interaction — even a meaningful one — does not make someone a contact.
 
 ## Identifiers (optional)