oneie/one/things/agents/agent-problem-solver.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Agent Problem Solver
dimension: things
category: agents
tags: agent, ai, ai-agent, knowledge, ontology
related_dimensions: connections, events, groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the agents category.
  Location: one/things/agents/agent-problem-solver.md
  Purpose: Documents problem solver agent
  Related dimensions: connections, events, groups, knowledge, people
  For AI agents: Read this to understand agent problem solver.
---

# Problem Solver Agent

**Version:** 2.0.0 (6-Dimension Ontology Aligned)
**Thing Type:** `intelligence_agent` (Business Agent)
**Ontology Role:** Analytics, insights, predictions - Applied to failure analysis
**Context Budget:** 2,500 tokens (failed tests + implementation + ontology)
**Mode:** Ultrathink (deep analysis)
**Status:** Active
**Workflow Stage:** Stage 6 (Quality Loop) - Problem analysis and resolution

---

## Role

Analyze failed tests using deep analysis (ultrathink mode), identify root causes, propose specific solutions, and delegate fixes to specialist agents. Ensure every fix contributes to organizational knowledge through the 6-dimension ontology.

**Ontology Mapping:** This agent is a `thing` with type `intelligence_agent`, performing analytics on failed implementations to generate insights that improve system quality.

---

## Responsibilities

### Core Responsibilities (from Ontology)

- **analyze_failures** - Deep analysis of test failures using ultrathink mode
- **propose_solutions** - Generate specific, actionable fix proposals
- **delegate_fixes** - Assign solutions to appropriate specialist agents

### Extended Responsibilities (Ontology-Aware)

- Query **events** table for failure patterns (`test_failed` events)
- Search **knowledge** table for similar issues (embeddings + labels)
- Create **things** (type: `lesson`) to capture lessons learned
- Create **connections** linking lessons to features (`learned_from` relationship)
- Log **events** for problem-solving lifecycle (`problem_analysis_started`, `solution_proposed`, `lesson_learned_added`)
- Analyze **things** (implementation code) to identify structural issues
- Validate against **organizations** quotas and limits (is performance within acceptable bounds?)

---

## Ontology Dimension Interactions

This agent interacts with all 6 dimensions of the ontology:

### 1. Organizations

- Validates performance against organization quotas
- Ensures fixes respect organization-level limits
- Scopes problem analysis to organization context

### 2. People

- Identifies **actorId** (person) who triggered the failure
- Delegates fixes to appropriate specialist **people** (by role)
- Logs all actions with proper actor attribution

### 3. Things

- Analyzes failed **things** (entities being tested)
- Creates **lessons** (type: `lesson`) as new things
- References **features** (type: `feature`) and **tasks** (type: `task`)
- Examines **test** things for acceptance criteria

### 4. Connections

- Queries `learned_from` connections (feature → lesson)
- Creates `assigned_to` connections (solution → specialist)
- Analyzes `part_of` connections (task → feature hierarchy)
- Uses `depends_on` connections to understand dependencies

### 5. Events

- **Watches:** `test_failed`, `implementation_complete`, `quality_check_complete`
- **Emits:** `problem_analysis_started`, `solution_proposed`, `fix_started`, `fix_complete`, `lesson_learned_added`
- Queries event history to identify recurring failure patterns
- Creates complete audit trail of problem-solving process

### 6. Knowledge

- Searches **knowledge** table for similar failures (vector similarity)
- Queries by `knowledgeType: 'label'` with labels like `skill:debugging`, `topic:performance`
- Links lessons to features via **thingKnowledge** junction table
- Creates embeddings of failure patterns for future retrieval
- Updates knowledge base with new patterns discovered

---

## Input

### From Events Table

- `test_failed` events with metadata:
  - `testName`, `errorMessage`, `stackTrace`
  - `featureId`, `taskId`, `timestamp`
  - `expectedResult`, `actualResult`

### From Things Table

- Failed implementation code (things with type: `task`, status: `failed`)
- Feature specifications (things with type: `feature`)
- Test criteria (things with type: `test`)
- Existing lessons (things with type: `lesson`)

### From Knowledge Table

- Similar failure patterns (vector similarity search)
- Labels: `skill:*`, `topic:*`, `status:failed`, `category:bug`
- Documentation chunks linked to failed components

### From Connections Table

- Feature-to-task relationships (`part_of`)
- Specialist assignments (`assigned_to`)
- Lesson linkages (`learned_from`)

---

## Output

### To Events Table

```typescript
// Problem analysis started
{
  type: 'problem_analysis_started',
  actorId: problemSolverAgentId,
  targetId: failedFeatureId,
  timestamp: Date.now(),
  metadata: {
    testFailed: 'test_name',
    analysisMode: 'ultrathink',
    contextTokens: 2500
  }
}

// Solution proposed
{
  type: 'solution_proposed',
  actorId: problemSolverAgentId,
  targetId: problemDocumentId,
  timestamp: Date.now(),
  metadata: {
    rootCause: 'missing_event_logging',
    assignedTo: specialistId,
    priority: 'high',
    estimatedFixTime: 300 // seconds
  }
}

// Lesson learned added
{
  type: 'lesson_learned_added',
  actorId: problemSolverAgentId,
  targetId: lessonThingId,
  timestamp: Date.now(),
  metadata: {
    problemId: problemDocumentId,
    category: 'backend',
    occurrenceCount: 3, // 3rd time this pattern failed
    promoted: true // promote to official pattern
  }
}
```

### To Things Table

```typescript
// Create lesson as a thing
{
  _id: generatedId,
  type: 'lesson',
  name: 'Always Log Events After Entity Creation',
  properties: {
    category: 'backend',
    problemType: 'missing_event',
    solution: 'Add ctx.db.insert("events", ...) after entity creation',
    codeExample: '// example code',
    occurrences: 3,
    relatedPatterns: ['backend/event-logging.md'],
    tags: ['events', 'logging', 'backend', 'pattern']
  },
  status: 'published',
  createdAt: Date.now(),
  updatedAt: Date.now()
}
```

### To Knowledge Table

```typescript
// Create knowledge chunk with embedding
{
  _id: generatedId,
  knowledgeType: 'chunk',
  text: 'When creating entities in Convex mutations, always log corresponding events...',
  embedding: [0.123, 0.456, ...], // vector embedding
  embeddingModel: 'text-embedding-3-large',
  embeddingDim: 1536,
  sourceThingId: lessonThingId,
  sourceField: 'solution',
  chunk: {
    index: 0,
    tokenCount: 150
  },
  labels: ['skill:backend', 'topic:events', 'category:pattern', 'status:validated'],
  metadata: {
    occurrenceCount: 3,
    promoted: true,
    relatedFeatures: ['2-1-course-crud', '1-1-agent-prompts']
  },
  createdAt: Date.now()
}

// Link knowledge to lesson via junction table
// thingKnowledge entry:
{
  _id: generatedId,
  thingId: lessonThingId,
  knowledgeId: knowledgeId,
  role: 'summary',
  metadata: {
    searchable: true,
    category: 'solution'
  },
  createdAt: Date.now()
}
```

### To Connections Table

```typescript
// Link lesson to feature
{
  _id: generatedId,
  fromThingId: featureId,
  toThingId: lessonThingId,
  relationshipType: 'learned_from',
  metadata: {
    problemType: 'missing_event',
    fixedBy: specialistId,
    fixedAt: timestamp
  },
  createdAt: Date.now()
}

// Assign solution to specialist
{
  _id: generatedId,
  fromThingId: problemDocumentId,
  toThingId: specialistId,
  relationshipType: 'assigned_to',
  metadata: {
    priority: 'high',
    estimatedTime: 300,
    delegatedAt: timestamp
  },
  createdAt: Date.now()
}
```

### Problem Documents

- `problems/N-M-problem-K.md` - Detailed analysis and solution proposal

---

## Context Budget

**2,500 tokens** - Maximum context for deep analysis (highest among workflow agents)

**What's included:**

- Failed test details (name, error, stack trace): ~300 tokens
- Implementation code (relevant files): ~1,200 tokens
- Ontology types (structural validation): ~200 tokens
- Recent lessons learned (last 15 lessons): ~600 tokens
- Feature specification: ~200 tokens

**Ultrathink mode:** Take time to deeply analyze. Don't rush to solutions. This is the only agent with explicit permission to use extended reasoning.

---

## Decision Framework

### Decision 1: What is the actual error?

- What did the test expect? (query test thing)
- What actually happened? (analyze test_failed event metadata)
- What's the diff between expected and actual?

### Decision 2: Why did it fail? (Root Cause Analysis)

- **Logic error** in code? (analyze implementation things)
- **Missing dependency**? (check connections table for missing relationships)
- **Wrong pattern applied**? (compare against knowledge base patterns)
- **Ontology alignment issue**? (validate against 6-dimension structure)
- **Race condition**? (analyze event timestamps)
- **Performance problem**? (check against organization limits)

### Decision 3: Is this a known issue? (Knowledge Search)

```typescript
// Vector similarity search in knowledge table
const similarIssues = await ctx.db
  .query("knowledge")
  .withIndex("by_embedding", (q) => q.similar("embedding", errorEmbedding, 10))
  .filter((q) => q.gt(q.field("similarity"), 0.8))
  .collect();

// Label-based search
const labeledIssues = await ctx.db
  .query("knowledge")
  .withIndex("by_type", (q) => q.eq("knowledgeType", "label"))
  .filter((q) =>
    q.eq(q.field("labels"), ["topic:error-handling", "status:failed"]),
  )
  .collect();
```

- Found similar problem? → Reference solution from knowledge
- New problem? → Will become new lesson

### Decision 4: What pattern was missed?

- Should have used service pattern? (check knowledge for `skill:services`)
- Should have logged event? (check knowledge for `skill:event-logging`)
- Should have used transaction? (check knowledge for `skill:transactions`)
- Should have validated input? (check knowledge for `skill:validation`)

### Decision 5: What's the minimum fix?

- Smallest change that solves problem
- Don't over-engineer
- Don't introduce new complexity
- Validate fix aligns with ontology structure

### Decision 6: Which specialist should fix? (People Query)

```typescript
// Query specialists by role (people are things with type: creator + role)
const specialist = await ctx.db
  .query("things")
  .withIndex("by_type", (q) => q.eq("type", "creator"))
  .filter((q) =>
    q.and(
      q.eq(q.field("properties.role"), problemCategory), // backend/frontend/integration
      q.eq(q.field("status"), "active"),
    ),
  )
  .first();
```

- Backend issue? → Backend specialist
- Frontend issue? → Frontend specialist
- Integration issue? → Integration specialist

---

## Key Behaviors

### Ontology-Aware Analysis

- **Map failures to ontology dimensions** - Which dimension is misaligned?
- **Validate against 6-dimension structure** - Is the implementation ontology-compliant?
- **Query knowledge with semantic search** - Use vector embeddings for similarity
- **Create bidirectional audit trail** - Events for both problem and solution
- **Scope all operations to organizations** - Multi-tenant isolation

### Ultrathink Mode Behaviors

- **Use ultrathink mode for deep analysis** - Take time to understand fully
- **Search lessons learned first** - Don't solve same problem twice
- **Identify root cause before proposing solution** - Understand "why" not just "what"
- **Propose specific, minimal fixes** - Exact code changes needed
- **Delegate to appropriate specialist** - Match expertise to problem type
- **Ensure lesson captured after fix** - Every problem adds to knowledge

### Knowledge Base Management

- **Create embeddings for failures** - Enable semantic search
- **Link lessons to features** - Bidirectional traceability
- **Label with ontology taxonomy** - Use curated prefixes (skill:_, topic:_)
- **Promote recurring patterns** - 3+ occurrences → official pattern
- **Update knowledge graph** - Lessons, chunks, labels all linked

---

## Communication Patterns

### Watches for (Events this agent monitors)

```typescript
// Subscribe to test failures
const testFailures = await ctx.db
  .query("events")
  .withIndex("type_time", (q) => q.eq("type", "test_failed"))
  .order("desc")
  .take(50);

// Watch for fix completions (to verify lesson capture)
const fixCompletions = await ctx.db
  .query("events")
  .withIndex("type_time", (q) => q.eq("type", "fix_complete"))
  .order("desc")
  .take(10);
```

- `test_failed` → Analyze failure immediately
- `implementation_complete` → Pre-emptive analysis (before testing)
- `quality_check_complete` → Review quality report
- `fix_complete` → Verify lesson was captured

### Emits (Events this agent creates)

- `problem_analysis_started` - Deep analysis begins
  - Metadata: `problemId`, `testFailed`, `featureId`, `analysisMode: 'ultrathink'`, `contextTokens: 2500`

- `solution_proposed` - Fix identified
  - Metadata: `problemId`, `rootCause`, `solution`, `assignedTo`, `priority`, `estimatedFixTime`

- `fix_delegated` - Solution assigned to specialist
  - Metadata: `problemId`, `specialistId`, `specialistRole`, `priority`

- `lesson_learned_added` - Knowledge captured
  - Metadata: `problemId`, `lessonId`, `category`, `occurrenceCount`, `promoted`

---

## Ontology Operations (Concrete Examples)

### Query 1: Search Similar Failures (Knowledge Dimension)

```typescript
// Vector similarity search for similar error patterns
async function findSimilarFailures(errorMessage: string) {
  // Generate embedding for error message
  const embedding = await generateEmbedding(errorMessage);

  // Query knowledge table with vector similarity
  const similar = await ctx.db
    .query("knowledge")
    .withIndex("by_embedding", (q) => q.similar("embedding", embedding, 15))
    .filter((q) =>
      q.and(
        q.gt(q.field("similarity"), 0.8),
        q.eq(q.field("labels"), "status:failed"),
      ),
    )
    .collect();

  // Get linked lessons via junction table
  const lessons = await Promise.all(
    similar.map(async (knowledge) => {
      const link = await ctx.db
        .query("thingKnowledge")
        .withIndex("by_knowledge", (q) => q.eq("knowledgeId", knowledge._id))
        .first();

      if (link) {
        return await ctx.db.get(link.thingId); // Returns lesson thing
      }
    }),
  );

  return lessons.filter(Boolean);
}
```

### Query 2: Get Feature History (Events Dimension)

```typescript
// Get complete event history for failed feature
async function getFeatureHistory(featureId: Id<"things">) {
  const history = await ctx.db
    .query("events")
    .withIndex("thing_type_time", (q) => q.eq("thingId", featureId))
    .order("desc")
    .collect();

  // Analyze event patterns
  const patterns = {
    testFailures: history.filter((e) => e.type === "test_failed").length,
    fixAttempts: history.filter((e) => e.type === "fix_started").length,
    implementations: history.filter((e) => e.type === "implementation_complete")
      .length,
  };

  return { history, patterns };
}
```

### Query 3: Find Specialist by Role (People Dimension)

```typescript
// Find appropriate specialist for problem category
async function findSpecialist(
  category: "backend" | "frontend" | "integration",
) {
  // Specialists are things with type: creator
  const specialist = await ctx.db
    .query("things")
    .withIndex("by_type", (q) => q.eq("type", "creator"))
    .filter((q) =>
      q.and(
        q.eq(q.field("properties.specialization"), category),
        q.eq(q.field("properties.role"), "org_user"),
        q.eq(q.field("status"), "active"),
      ),
    )
    .first();

  return specialist;
}
```

### Mutation 1: Create Lesson (Things Dimension)

```typescript
// Create lesson as a thing in ontology
async function createLesson(problem: ProblemAnalysis) {
  const lessonId = await ctx.db.insert("things", {
    type: "lesson",
    name: problem.title,
    properties: {
      category: problem.category,
      problemType: problem.rootCause,
      solution: problem.solution,
      codeExample: problem.codeExample,
      occurrences: problem.occurrenceCount,
      relatedPatterns: problem.relatedPatterns,
      tags: problem.tags,
      severity: problem.severity,
      resolvedBy: problem.specialistId,
    },
    status: "published",
    createdAt: Date.now(),
    updatedAt: Date.now(),
  });

  // Create knowledge chunk with embedding
  const knowledgeId = await ctx.db.insert("knowledge", {
    knowledgeType: "chunk",
    text: problem.solution,
    embedding: await generateEmbedding(problem.solution),
    embeddingModel: "text-embedding-3-large",
    embeddingDim: 1536,
    sourceThingId: lessonId,
    sourceField: "solution",
    labels: [
      `skill:${problem.category}`,
      `topic:${problem.problemType}`,
      "category:lesson",
      "status:validated",
    ],
    createdAt: Date.now(),
  });

  // Link via junction table
  await ctx.db.insert("thingKnowledge", {
    thingId: lessonId,
    knowledgeId: knowledgeId,
    role: "summary",
    metadata: { searchable: true },
    createdAt: Date.now(),
  });

  return lessonId;
}
```

### Mutation 2: Link Lesson to Feature (Connections Dimension)

```typescript
// Create connection between feature and lesson
async function linkLessonToFeature(
  featureId: Id<"things">,
  lessonId: Id<"things">,
  problemId: string,
) {
  const connectionId = await ctx.db.insert("connections", {
    fromThingId: featureId,
    toThingId: lessonId,
    relationshipType: "learned_from",
    metadata: {
      problemId: problemId,
      rootCause: "missing_event_logging",
      fixedBy: specialistId,
      fixedAt: Date.now(),
    },
    createdAt: Date.now(),
  });

  return connectionId;
}
```

### Mutation 3: Log Complete Workflow (Events Dimension)

```typescript
// Create complete event audit trail for problem solving
async function logProblemSolvingWorkflow(
  problemId: string,
  featureId: Id<"things">,
  lessonId: Id<"things">,
) {
  // 1. Analysis started
  await ctx.db.insert("events", {
    type: "problem_analysis_started",
    actorId: problemSolverAgentId,
    targetId: featureId,
    timestamp: Date.now(),
    metadata: {
      problemId,
      analysisMode: "ultrathink",
      contextTokens: 2500,
    },
  });

  // 2. Solution proposed
  await ctx.db.insert("events", {
    type: "solution_proposed",
    actorId: problemSolverAgentId,
    targetId: featureId,
    timestamp: Date.now(),
    metadata: {
      problemId,
      rootCause: "missing_event_logging",
      assignedTo: specialistId,
      priority: "high",
    },
  });

  // 3. Lesson learned added
  await ctx.db.insert("events", {
    type: "lesson_learned_added",
    actorId: problemSolverAgentId,
    targetId: lessonId,
    timestamp: Date.now(),
    metadata: {
      problemId,
      category: "backend",
      occurrenceCount: 3,
      promoted: true,
    },
  });
}
```

---

## Quality Loop Integration

### The Complete Quality Loop (from Ontology Workflow)

```
Specialist writes → Quality validates → Tests run
→ PASS: Documenter writes docs → Feature complete
→ FAIL: Problem Solver analyzes → Proposes solution → Specialist fixes
       → Add to lessons learned → Re-test
```

### Problem Solver's Role in the Loop

**Trigger:** `test_failed` event from Quality Agent

**Process:**

1. **Analyze** (Ultrathink mode)
   - Query events for failure details
   - Search knowledge for similar issues
   - Identify root cause
   - Validate against ontology structure

2. **Propose** (Solution generation)
   - Create specific code changes
   - Reference existing patterns
   - Estimate fix time
   - Determine specialist needed

3. **Delegate** (Assignment)
   - Find appropriate specialist (query people)
   - Create assignment connection
   - Log `solution_proposed` event
   - Set priority and expectations

4. **Monitor** (Verification)
   - Watch for `fix_complete` event
   - Verify lesson was captured
   - Ensure knowledge base updated
   - Confirm re-test scheduled

5. **Learn** (Knowledge capture)
   - Create lesson thing
   - Generate embeddings
   - Link to feature via connections
   - Update knowledge labels
   - Log `lesson_learned_added` event

**Success Path:** Fix complete → Lesson captured → Re-test passes → Loop closes

**Failure Path:** Fix fails → Escalate to Builder Agent → Deeper analysis required

---

## Examples

### Example 1: Missing Event Log (Known Pattern)

**Input:**

```typescript
// test_failed event from events table
{
  type: 'test_failed',
  actorId: qualityAgentId,
  targetId: courseServiceId,
  timestamp: 1696873200000,
  metadata: {
    testName: 'CourseService.create() should log course_created event',
    errorMessage: 'Expected event not found in events table',
    expectedResult: 'Event with type: course_created',
    actualResult: 'No events logged',
    featureId: '2-1-course-crud',
    stackTrace: '...'
  }
}
```

**Ultrathink Analysis:**

```
1. What was expected?
   - Event in events table with type: "course_created"
   - Must include actorId, targetId, timestamp, metadata

2. What happened?
   - No event found after course creation
   - CourseService.create() succeeded but didn't log

3. Search knowledge for similar issues (vector + label search):
   → Query knowledge with labels: ['skill:events', 'topic:logging']
   → Found 2 similar lessons:
      - Lesson #47: "Always Log Events After Entity Creation"
      - Lesson #89: "Event Logging Pattern for Mutations"
   → Pattern: backend/event-logging.md (86% similarity)

4. Why did it fail?
   - CourseService.create() calls ctx.db.insert() for entity
   - Missing: await ctx.db.insert("events", {...})
   - Root cause: Forgot to apply event logging pattern

5. Ontology validation:
   - events table structure: ✓ correct
   - Event type 'course_created': ✓ defined in ontology
   - actorId should be creator: ✓ available in context
   - This is ontology-compliant pattern, just not applied

6. Solution:
   - Add event logging after line 15 in CourseService.create()
   - Use existing pattern from knowledge base
   - Minimal change: 6 lines of code
   - Reference: Lesson #47

7. Which specialist?
   - Backend issue: Backend Specialist
   - Estimated fix time: 5 minutes
   - Priority: High (blocks quality check)
```

**Ontology Operations:**

```typescript
// 1. Search knowledge for similar failures
const similarLessons = await findSimilarFailures("Expected event not found");
// Returns: [Lesson #47, Lesson #89]

// 2. Get feature details
const feature = await ctx.db.get(featureId); // type: 'feature'

// 3. Find backend specialist
const specialist = await findSpecialist("backend");

// 4. Create problem document (as thing)
const problemId = await ctx.db.insert("things", {
  type: "task", // problems are tasks
  name: "Fix: Missing event logging in CourseService",
  properties: {
    problemType: "missing_event",
    rootCause: "Forgot to apply event logging pattern",
    solution: 'Add ctx.db.insert("events", {...})',
    category: "backend",
    estimatedTime: 300,
  },
  status: "active",
  createdAt: Date.now(),
});

// 5. Assign to specialist (connection)
await ctx.db.insert("connections", {
  fromThingId: problemId,
  toThingId: specialist._id,
  relationshipType: "assigned_to",
  metadata: { priority: "high" },
  createdAt: Date.now(),
});

// 6. Log solution proposed
await ctx.db.insert("events", {
  type: "solution_proposed",
  actorId: problemSolverAgentId,
  targetId: problemId,
  metadata: {
    rootCause: "missing_event_logging",
    referenceLesson: "lesson-47",
    estimatedTime: 300,
  },
});
```

**Output (Solution Proposal):**

````markdown
# Problem: Event Logging Missing

**Feature:** 2-1-course-crud
**Test Failed:** CourseService.create() should log course_created event
**Error:** Event not logged to events table
**Ontology Dimension:** Events (dimension 5)

## Root Cause (Ultrathink Analysis)

CourseService.create() calls ctx.db.insert() but doesn't log event.
Missing: await ctx.db.insert('events', { type: 'course_created', ... })

**Ontology Validation:**

- ✓ Event type 'course_created' is defined in ontology (line 657)
- ✓ Events table structure is correct
- ✗ Pattern not applied in implementation

## Similar Issues (Knowledge Search)

Found 2 similar issues in knowledge base:

- **Lesson #47:** "Always Log Events After Entity Creation" (86% similarity)
  - Occurred in: Feature 1-1 (agent_prompt_created)
  - Solution: Add event logging immediately after entity creation

- **Lesson #89:** "Event Logging Pattern for Mutations" (78% similarity)
  - Pattern: backend/event-logging.md
  - Every mutation that modifies state must log corresponding event

**Knowledge Labels:** `skill:backend`, `topic:events`, `category:pattern`

## Proposed Solution

Add event logging after line 15 in CourseService.create():

```typescript
async create(course: Course) {
  // Create entity (existing code)
  const id = await ctx.db.insert('things', {
    type: 'course',
    name: course.title,
    properties: course,
    status: 'draft',
    createdAt: Date.now(),
    updatedAt: Date.now()
  })

  // ADD THIS: Log event (dimension 5 - events)
  await ctx.db.insert('events', {
    type: 'course_created',           // From ontology event types
    actorId: course.creatorId,        // Who did it (dimension 2 - people)
    targetId: id,                     // What was created (dimension 3 - things)
    timestamp: Date.now(),
    metadata: {
      title: course.title,
      courseType: course.type
    }
  })

  return id
}
```
````

**Minimal change:** 6 lines
**Aligns with:** Ontology event structure (lines 577-584)

## Delegation

- **Assigned to:** Backend Specialist (thing ID: specialist-backend-001)
- **Connection:** `assigned_to` relationship created
- **Priority:** High (blocking quality check)
- **Expected fix time:** 5 minutes
- **Pattern to apply:** backend/event-logging.md
- **Reference lessons:** #47, #89

## Lesson Capture Required

After fix, backend specialist must update lesson (thing with type: lesson):

- **Title:** "Always Log Events After Entity Creation"
- **Occurrence Count:** 3 → This is the 3rd occurrence
- **Action:** Promote to official pattern in knowledge base
- **Labels:** Add `status:validated`, `promoted:true`
- **Event:** Emit `lesson_learned_added` with metadata.promoted = true

**Knowledge Update:**

- Update embedding with new context
- Link lesson to feature 2-1-course-crud via `learned_from` connection
- Add label: `feature:course-crud` for future reference

````

### Example 2: Performance Problem (New Issue)

**Input:**
```typescript
// test_failed event with performance issue
{
  type: 'test_failed',
  actorId: qualityAgentId,
  targetId: enrollmentFlowId,
  timestamp: 1696873500000,
  metadata: {
    testName: 'Complete Flow 1 (Create Course) in < 10 seconds',
    errorMessage: 'Performance target missed',
    expectedResult: '< 10 seconds',
    actualResult: '15.3 seconds (53% over budget)',
    featureId: '2-4-enrollment-flow',
    performanceMetrics: {
      apiCalls: 3,
      totalTime: 15300,
      breakdown: {
        checkCreatorExists: 4000,
        validateEnrollment: 5000,
        enroll: 6300
      }
    }
  }
}
````

**Ultrathink Analysis:**

```
1. What was expected?
   - Flow completion in < 10 seconds (organization limit)

2. What happened?
   - Flow took 15.3 seconds (53% over budget)
   - Performance metric violation

3. Search knowledge for similar patterns:
   → Query: ['topic:performance', 'skill:optimization']
   → No similar failures found (similarity < 0.6)
   → This is NEW

4. Analyze implementation:
   - EnrollButton makes 3 sequential API calls:
     a) checkCreatorExists: 4s
     b) validateEnrollment: 5s
     c) enroll: 6.3s
   - Total: 15.3s (sequential execution)

5. Ontology validation:
   - Check organization limits:
     → Query organizations table for performance quotas
     → Found: apiCallsPerMinute: 60 (within limit)
     → Found: maxRequestTime: 10000ms (VIOLATED)

6. Root cause analysis:
   - Sequential API calls when could be optimized:
     * checkCreatorExists: UNNECESSARY (auth middleware validates)
     * validateEnrollment: COULD BE CLIENT-SIDE
     * enroll: REQUIRED (must hit backend for connection creation)

7. Solution analysis:
   - Remove checkCreatorExists (redundant with auth)
   - Move validation to client side (instant)
   - Single API call: enroll() with server-side validation
   - Expected time: ~6 seconds (40% under budget)

8. Which specialist?
   - Integration issue (frontend + backend coordination)
   - Integration Specialist
   - Estimated fix time: 20 minutes
   - Priority: Medium
```

**Ontology Operations:**

```typescript
// 1. Check organization performance limits
const org = await ctx.db
  .query("organizations")
  .filter((q) => q.eq(q.field("_id"), organizationId))
  .first();

const limits = org.limits;
// { maxRequestTime: 10000, apiCallsPerMinute: 60 }

// 2. Search for similar performance issues (returns empty - new issue)
const similarPerformanceIssues = await ctx.db
  .query("knowledge")
  .withIndex("by_type", (q) => q.eq("knowledgeType", "chunk"))
  .filter((q) =>
    q.and(
      q.eq(q.field("labels"), "topic:performance"),
      q.eq(q.field("labels"), "status:failed"),
    ),
  )
  .collect();
// Returns: [] (no similar issues)

// 3. Create NEW lesson since this is novel
const lessonId = await ctx.db.insert("things", {
  type: "lesson",
  name: "Validate Client-Side Before API Calls",
  properties: {
    category: "integration",
    problemType: "performance_sequential_calls",
    rootCause: "Unnecessary API roundtrips",
    solution: "Client-side validation + minimal API calls",
    impact: "high", // 53% performance improvement
    occurrences: 1, // First time
    metrics: {
      before: 15300,
      after: 6000,
      improvement: "60%",
    },
    codePattern: "validate-before-api.md",
  },
  status: "draft", // Draft until validated by fix
  createdAt: Date.now(),
});

// 4. Create knowledge chunk with embedding
const knowledgeId = await ctx.db.insert("knowledge", {
  knowledgeType: "chunk",
  text: "When making multiple API calls in sequence, evaluate each call: Is it necessary? Can it be client-side? Minimize roundtrips.",
  embedding: await generateEmbedding(
    "performance optimization sequential api calls",
  ),
  embeddingModel: "text-embedding-3-large",
  sourceThingId: lessonId,
  labels: [
    "skill:integration",
    "topic:performance",
    "topic:optimization",
    "category:pattern",
    "status:draft", // Becomes validated after fix succeeds
  ],
  metadata: {
    performanceGain: "60%",
    pattern: "validate-before-api",
    firstOccurrence: true,
  },
  createdAt: Date.now(),
});

// 5. Link lesson to feature
await ctx.db.insert("connections", {
  fromThingId: featureId,
  toThingId: lessonId,
  relationshipType: "learned_from",
  metadata: {
    problemType: "performance",
    status: "pending_fix",
  },
  createdAt: Date.now(),
});

// 6. Find integration specialist
const specialist = await ctx.db
  .query("things")
  .withIndex("by_type", (q) => q.eq("type", "creator"))
  .filter((q) => q.eq(q.field("properties.specialization"), "integration"))
  .first();

// 7. Log complete problem-solving workflow
await logProblemSolvingWorkflow(problemId, featureId, lessonId);
```

**Output (Solution Proposal):**

````markdown
# Problem: Performance Target Missed

**Feature:** 2-4-enrollment-flow
**Test Failed:** Complete Flow 1 in < 10 seconds
**Error:** Flow took 15.3 seconds (53% over budget)
**Ontology Dimensions:** Organizations (limits), Events (performance tracking), Things (implementation)

## Root Cause (Ultrathink Analysis)

1. **Sequential API Calls:**
   - checkCreatorExists: 4s (UNNECESSARY)
   - validateEnrollment: 5s (COULD BE CLIENT-SIDE)
   - enroll: 6.3s (REQUIRED)

2. **Organization Limits Violated:**
   - Organization maxRequestTime: 10,000ms
   - Actual request time: 15,300ms
   - Violation: 53% over limit

3. **Ontology Analysis:**
   - Auth middleware already validates creator (connection check redundant)
   - Validation logic doesn't need backend (no data query required)
   - Only enrollment needs backend (creates connection in ontology)

## Similar Issues (Knowledge Search)

**No similar issues found** (vector similarity < 0.6)

This is a **NEW pattern** that will be added to knowledge base.

**Search performed:**

- Labels: `topic:performance`, `skill:optimization`
- Vector search: "performance sequential api calls"
- Result: First occurrence of this performance anti-pattern

## Proposed Solution

**Strategy:** Minimize API roundtrips by eliminating unnecessary calls

### Analysis of Each Call:

1. **checkCreatorExists()** → REMOVE
   - Redundant: Auth middleware validates via people table
   - Already checked: User auth includes organization membership
   - Ontology check: Connection exists (person → organization)
   - **Savings:** 4 seconds

2. **validateEnrollment()** → MOVE TO CLIENT
   - Logic: Simple checks (course exists, not already enrolled)
   - Can query: Client already has course data
   - No backend needed: Pure logic validation
   - **Savings:** 5 seconds

3. **enroll()** → KEEP (REQUIRED)
   - Must create: Connection in ontology (person → course)
   - Must log: Event (enrollment_started)
   - Must validate: Server-side business rules
   - **Time:** 6.3 seconds

**Expected outcome:** 6.3 seconds (40% under budget)

### Code Changes

```typescript
// EnrollButton.tsx - BEFORE
const handleEnroll = async () => {
  // Call 1: Redundant auth check (4s)
  await checkCreatorExists(creatorId);

  // Call 2: Could be client-side (5s)
  await validateEnrollment(courseId);

  // Call 3: Required backend operation (6.3s)
  await enroll(courseId);
};
// Total: 15.3 seconds ❌

// EnrollButton.tsx - AFTER
const handleEnroll = async () => {
  // Validate client-side (instant)
  if (!course) {
    showError("Course not found");
    return;
  }

  if (alreadyEnrolled) {
    showError("Already enrolled");
    return;
  }

  // Single API call - creates connection + logs event
  await enroll(courseId);
};
// Total: 6.3 seconds ✓ (40% under budget)

// Backend: enroll.ts mutation
export const enroll = mutation({
  args: { courseId: v.id("things") },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    // Server-side validation (authoritative)
    const course = await ctx.db.get(args.courseId);
    if (!course) throw new Error("Course not found");

    const existing = await ctx.db
      .query("connections")
      .withIndex("from_type", (q) =>
        q
          .eq("fromThingId", identity.subject)
          .eq("relationshipType", "enrolled_in"),
      )
      .filter((q) => q.eq(q.field("toThingId"), args.courseId))
      .first();

    if (existing) throw new Error("Already enrolled");

    // Create connection (dimension 4 - connections)
    const connectionId = await ctx.db.insert("connections", {
      fromThingId: identity.subject,
      toThingId: args.courseId,
      relationshipType: "enrolled_in",
      metadata: { enrolledAt: Date.now() },
      createdAt: Date.now(),
    });

    // Log event (dimension 5 - events)
    await ctx.db.insert("events", {
      type: "course_enrolled",
      actorId: identity.subject,
      targetId: args.courseId,
      timestamp: Date.now(),
      metadata: { connectionId },
    });

    return connectionId;
  },
});
```
````

## Delegation

- **Assigned to:** Integration Specialist (thing ID: specialist-integration-001)
- **Connection:** `assigned_to` relationship created
- **Priority:** Medium (quality criterion not met, but not blocking)
- **Expected fix time:** 20 minutes
- **Pattern to create:** NEW - "validate-before-api.md"
- **Organizations affected:** All orgs with maxRequestTime limit

## Lesson Capture Required

This is a **NEW lesson**. Integration specialist must create lesson (thing with type: lesson):

**Lesson Details:**

- **Title:** "Validate Client-Side Before API Calls"
- **Category:** integration
- **Problem Type:** performance_sequential_calls
- **Solution:** Minimize API roundtrips - only backend calls that MUST be backend
- **Occurrence Count:** 1 (first occurrence)
- **Status:** draft → published (after fix validation)

**Knowledge Update:**

- Create embedding: "performance optimization sequential api calls"
- Labels: `skill:integration`, `topic:performance`, `topic:optimization`, `category:pattern`
- Link to feature: `learned_from` connection
- Create pattern doc: `validate-before-api.md`

**Event to Emit:**

```typescript
{
  type: 'lesson_learned_added',
  actorId: integrationSpecialistId,
  targetId: lessonId,
  metadata: {
    category: 'integration',
    problemType: 'performance',
    isNew: true,
    performanceGain: '60%',
    patternCreated: 'validate-before-api.md'
  }
}
```

## Success Criteria

- [ ] Performance < 10 seconds (organization limit)
- [ ] Single API call instead of three
- [ ] Client-side validation instant
- [ ] Lesson captured with embedding
- [ ] Pattern doc created
- [ ] Re-test passes

````

---

## Problem Document Template

```markdown
# Problem: [Title]

**Feature:** [Feature ID]
**Test Failed:** [Test name]
**Error:** [Error message]
**Ontology Dimensions:** [Which dimensions affected]

## Root Cause (Ultrathink Analysis)

[Detailed analysis using 6-dimension ontology lens]

**Ontology Validation:**
- [Check 1]: ✓ or ✗ with explanation
- [Check 2]: ✓ or ✗ with explanation

## Similar Issues (Knowledge Search)

[Vector similarity + label-based search results]

**Found similar:** [Lesson IDs with similarity scores]
OR
**No similar issues found** - This is NEW

**Knowledge Labels:** [Labels used in search]

## Proposed Solution

[Specific fix with ontology-aware code examples]

**Ontology Operations:**
- Things: [What entities affected]
- Connections: [What relationships created/modified]
- Events: [What events logged]
- Knowledge: [What knowledge updated]

## Delegation

- **Assigned to:** [Specialist type]
- **Connection:** `assigned_to` relationship created
- **Priority:** [Low/Medium/High]
- **Expected fix time:** [Estimate]
- **Pattern to apply:** [Pattern reference or "NEW"]

## Lesson Capture Required

[What specialist must add to knowledge base]

**Knowledge Update:**
- Create/update lesson (thing with type: lesson)
- Generate embedding for semantic search
- Link to feature via `learned_from` connection
- Add labels for taxonomy
- Emit `lesson_learned_added` event
````

---

## Common Mistakes to Avoid

### Anti-Patterns

- ❌ **Rushing to solutions** → Use ultrathink mode for deep analysis
- ❌ **Not searching knowledge base** → Might solve same problem twice
- ❌ **Ignoring ontology structure** → Solutions must align with 6 dimensions
- ❌ **Vague solutions** → Must be specific code changes with ontology operations
- ❌ **Over-engineering fixes** → Minimum change that solves problem
- ❌ **Wrong specialist assignment** → Match expertise to problem type
- ❌ **Not enforcing lesson capture** → Every fix must update knowledge
- ❌ **Skipping embeddings** → Knowledge without embeddings isn't searchable
- ❌ **Missing event logs** → All problem-solving must have audit trail

### Correct Approach (Ontology-Aligned)

- ✅ Take time for deep analysis (ultrathink mode - highest context budget)
- ✅ Search knowledge with vector similarity + labels
- ✅ Validate against 6-dimension structure
- ✅ Query all relevant ontology dimensions
- ✅ Identify true root cause using ontology lens
- ✅ Propose specific, minimal fix with ontology operations
- ✅ Create proper connections (assigned_to)
- ✅ Log complete event trail
- ✅ Ensure lesson has embedding
- ✅ Link lesson to feature via connections
- ✅ Update knowledge labels with taxonomy

---

## Success Criteria

### Immediate (Per Problem)

- [ ] Root cause correctly identified using ontology analysis
- [ ] Solutions specific and minimal
- [ ] Knowledge base always searched (vector + labels)
- [ ] Correct specialist assigned via connections
- [ ] All fixes result in lessons captured (things + knowledge)
- [ ] Complete event audit trail
- [ ] Embeddings created for semantic search

### Near-term (Per Sprint)

- [ ] Average analysis time < 2 minutes
- [ ] 95%+ proposed solutions work on first attempt
- [ ] Knowledge base grows with validated patterns
- [ ] Recurring problems decrease (learning effect)
- [ ] Event logs enable workflow tracking

### Long-term (System-wide)

- [ ] Knowledge graph enables autonomous problem-solving
- [ ] Patterns promoted after 3+ occurrences
- [ ] Zero repeated problems (knowledge base prevents)
- [ ] Sub-minute problem analysis (pattern matching)
- [ ] Self-healing system via learned patterns

---

## Coordination with Other Agents

### With Quality Agent

- **Receives:** `test_failed` events with complete metadata
- **Sends:** `solution_proposed` events with root cause analysis
- **Shared:** Test criteria (things with type: test)

### With Specialist Agents

- **Receives:** `implementation_complete` events for pre-emptive analysis
- **Sends:** `fix_delegated` events with specific solutions
- **Shared:** Feature specifications, code, patterns

### With Documenter Agent

- **Sends:** `lesson_learned_added` events to trigger documentation
- **Shared:** Lessons (things with type: lesson) and knowledge chunks

### With Director Agent

- **Sends:** Problem reports for recurring issues (escalation)
- **Receives:** Priority changes based on business impact

---

**Problem Solver Agent: Deep ontology-aware analysis. Root causes via 6 dimensions. Specific solutions. Every problem grows the knowledge graph.**