Back to catalog

ai-enhancement

AI-powered blindspot detection and insight generation from graph structure. Use when analyzing content for missing elements, discovering non-obvious connections, or identifying conceptual opportunities.

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• Updated: 2025-11-22

• Source: mrhpython/Soulfield

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: ai-enhancement
description: AI-powered blindspot detection and insight generation from graph structure. Use when analyzing content for missing elements, discovering non-obvious connections, or identifying conceptual opportunities.
---

# AI Enhancement Skill

**Purpose:** AI-powered blindspot detection and insight generation from graph structure

**Backend:** `backend/services/graph-ai-enhancer.cjs` (269 lines)

**Status:** ✅ Operational (implemented Phase 3)

---

## What This Skill Does

Sends graph structure (not raw text) to Claude API for AI-generated insights about blindspots, connections, and conceptual opportunities.

**Key Capabilities:**
- Graph structure extraction (clusters, gaps, metrics)
- AI insight generation (blindspots, connections, opportunities)
- Structured JSON response parsing
- Multi-graph comparison support
- Graceful fallback on API errors

---

## When to Use This Skill

Use AI enhancement when:
- User requests "what am I missing?"
- Need deeper analysis beyond structural metrics
- Identifying conceptual blindspots
- Prioritizing which gaps to bridge first
- Discovering non-obvious connections

---

## How It Works

### 1. Graph Structure Extraction

Extracts structured data from analysis:

**Cluster Information:**
- ID and size
- Top 5 keywords per cluster
- Influence (average centrality)
- Cohesion (internal connectivity)

**Gap Information:**
- Source and target clusters
- Gap score (0-1)
- Severity level (critical/major/minor)
- Gap type (structural/topical/semantic/logical)

**Top Concepts (VIP Nodes):**
- Concept names
- Diversivity scores
- Node types

**Graph Metrics:**
- Node count, cluster count, gap count
- Cognitive state (BIAS/FOCUSED/DIVERSE/DISPERSED)
- Modularity, entropy, density
- Evolution stage and intent

---

### 2. AI Prompt Generation

Sends structured prompt to Claude API:

```javascript
**GRAPH STRUCTURE:**
{
  nodeCount: 16,
  clusterCount: 4,
  gapCount: 3,
  cognitiveState: "FOCUSED",
  modularity: 0.269,
  entropy: 0.931,
  clusters: [...],
  gaps: [...]
}

**YOUR TASK:**
Generate 5 insights focused on: blindspots, connections, opportunities

**FOCUS AREAS:**
- BLINDSPOTS: What topics/concepts are missing?
- CONNECTIONS: What surprising connections could be made?
- OPPORTUNITIES: What new directions could exploration take?

**OUTPUT FORMAT:**
Return JSON array of insights with type, severity, insight, reasoning, action
```

---

### 3. AI Response Parsing

Extracts JSON from Claude response:

**Expected Format:**
```json
[
  {
    "type": "blindspot",
    "severity": "high",
    "insight": "Marketing activities disconnected from performance measurement",
    "reasoning": "Cluster 0 (marketing, campaigns) has major gap to cluster 2 (metrics, analytics) with distance 3 hops",
    "action": "Add bridging concepts: KPIs, conversion tracking, ROI measurement"
  },
  {
    "type": "connection",
    "severity": "medium",
    "insight": "Strategy and execution lack intermediate implementation steps",
    "reasoning": "Gap between cluster 0 and cluster 1 indicates missing tactical layer",
    "action": "Develop implementation frameworks connecting strategy to tactics"
  }
]
```

**Validation:**
- Filters insights with required fields (type, insight, reasoning, action)
- Extracts JSON array from response (handles markdown code fences)
- Returns empty array on parse errors

---

## Focus Areas

### Blindspots
**Definition:** Missing topics, underrepresented perspectives, conceptual gaps

**AI Looks For:**
- Clusters with low influence but high potential
- Missing intermediate concepts between clusters
- Topics common in domain but absent from graph
- Underexplored periphery concepts

**Example Insight:**
```
Type: blindspot
Severity: high
Insight: "Implementation layer missing between strategy and execution"
Reasoning: "Gap score 0.702 between clusters 0→1 with no intermediate bridging concepts"
Action: "Add tactical planning concepts: timelines, resources, milestones"
```

### Connections
**Definition:** Surprising connections, gap bridging priorities, non-obvious relationships

**AI Looks For:**
- High-value gaps to bridge first
- Cross-cluster connections with high potential
- Conceptual relationships not obvious from structure
- Opportunities to link isolated clusters

**Example Insight:**
```
Type: connection
Severity: medium
Insight: "Revenue and management clusters weakly connected"
Reasoning: "3-hop distance between financial metrics and strategic decisions"
Action: "Bridge via financial reporting, performance dashboards, executive summaries"
```

### Opportunities
**Definition:** New exploration directions, diversity improvements, conceptual expansion

**AI Looks For:**
- Areas to increase cognitive diversity
- New directions for exploration (based on evolution stage)
- Concepts to deepen or expand
- Balance improvements (explore vs focus)

**Example Insight:**
```
Type: opportunity
Severity: low
Insight: "Expand content cluster specificity"
Reasoning: "Cluster 2 has high modularity (0.431) suggesting room for deeper exploration"
Action: "Add subcategories: SEO content, social content, email content"
```

---

## API Integration

**Endpoint:** `https://api.anthropic.com/v1/messages`

**Model:** `claude-sonnet-4-5-20250929` (default)

**Parameters:**
- Max tokens: 2000
- Temperature: 0.7 (balanced creativity)
- Timeout: 60 seconds

**Headers:**
```javascript
{
  'x-api-key': process.env.ANTHROPIC_API_KEY,
  'anthropic-version': '2023-06-01',
  'content-type': 'application/json'
}
```

**Authentication:**
- Requires `ANTHROPIC_API_KEY` environment variable
- Falls back to empty insights if missing
- Returns `{ fallback: true, error: 'No API key' }` on failure

---

## Output Structure

```javascript
{
  insights: [
    {
      type: "blindspot|connection|opportunity",
      severity: "high|medium|low",
      insight: "One-sentence summary",
      reasoning: "Why this matters (cites clusters/gaps/metrics)",
      action: "Specific actionable next step"
    }
  ],
  metadata: {
    model: "claude-sonnet-4-5-20250929",
    focusAreas: ["blindspots", "connections", "opportunities"],
    graphMetrics: {
      nodes: 16,
      clusters: 4,
      gaps: 3,
      state: "FOCUSED"
    },
    timestamp: "2025-11-06T..."
  }
}
```

**Error Response:**
```javascript
{
  insights: [],
  error: "Error message",
  fallback: true
}
```

---

## Integration Points

**Called by:**
- `backend/services/agent-graph-service.cjs:154-164` (optional, only if API key present)

**Depends on:**
- Complete graph analysis from local-graph-analysis.cjs
- Claude API authentication
- Graph structure (clusters, gaps, metrics, evolution)

**Outputs:**
- AI insights array
- Metadata (model, metrics, timestamp)
- Error info (if failed)

---

## Performance

- **Speed:** ~3-5 seconds per analysis (Claude API latency)
- **Cost:** ~$0.01 per analysis (2000 tokens)
- **Accuracy:** Varies (AI-generated, not deterministic)

**Cost Estimate:**
- 100 analyses/day = $1/day = $30/month
- Recommend limiting to high-value analyses

---

## Testing

```bash
# Test AI enhancement with graph analysis
node -e "
const { analyzeForAgent } = require('./backend/services/agent-graph-service.cjs');
(async () => {
  const result = await analyzeForAgent('finance', 'revenue projections cost structure burn rate management metrics');

  if (result.aiInsights?.insights?.length > 0) {
    console.log('AI Insights generated:', result.aiInsights.insights.length);
    result.aiInsights.insights.forEach((insight, i) => {
      console.log(\`\${i+1}. [\${insight.type}] [\${insight.severity}] \${insight.insight}\`);
      console.log(\`   Reasoning: \${insight.reasoning}\`);
      console.log(\`   Action: \${insight.action}\`);
    });
  } else {
    console.log('AI enhancement skipped (no API key or error)');
  }
})();
"

# Expected output (with API key):
# AI Insights generated: 2
# 1. [blindspot] [high] Marketing activities disconnected from performance measurement
#    Reasoning: Cluster 0 has major gap to cluster 2 (distance 3 hops)
#    Action: Add bridging concepts: KPIs, conversion tracking, ROI
```

---

## Multi-Graph Comparison

**Feature:** Compare AI insights across multiple analyses

```javascript
const { enhanceMultipleGraphs } = require('./backend/services/graph-ai-enhancer.cjs');

const results = await enhanceMultipleGraphs([analysis1, analysis2, analysis3]);

// Output:
{
  individual: [ /* per-graph insights */ ],
  comparative: {
    total: 6,
    byType: { blindspot: 3, connection: 2, opportunity: 1 },
    bySeverity: { high: 2, medium: 3, low: 1 },
    commonThemes: [
      { keyword: "implementation", count: 3 },
      { keyword: "metrics", count: 2 }
    ]
  }
}
```

---

## Real-World Examples

**@finance (Financial Analysis):**
```
2 AI insights generated:

1. [blindspot] [high]
   Insight: "Implementation layer missing between revenue and management"
   Reasoning: "Major gap (score=0.805) between cluster 0 (revenue, projections) and cluster 3 (management) with no intermediate tactical concepts"
   Action: "Add financial reporting, dashboard metrics, executive summaries"

2. [opportunity] [medium]
   Insight: "Expand unit economics cluster depth"
   Reasoning: "Cluster 1 (analysis, unit, economics, cash) has moderate modularity (0.166) suggesting room for deeper exploration"
   Action: "Add subcategories: CAC, LTV, payback period, margin analysis"
```

**@marketing (Campaign Strategy):**
```
2 AI insights generated:

1. [blindspot] [high]
   Insight: "Execution layer disconnected from strategy"
   Reasoning: "Gap between cluster 0 (strategy, planning) and cluster 1 (campaigns, content) indicates missing implementation bridge"
   Action: "Add tactical planning: campaign briefs, timelines, resource allocation"

2. [connection] [medium]
   Insight: "Link product positioning to customer acquisition"
   Reasoning: "Clusters 0 and 2 separated by 2 hops, potential for stronger positioning-to-conversion linkage"
   Action: "Develop value proposition frameworks connecting product features to customer pain points"
```

**@seo (Search Optimization):**
```
2 AI insights generated:

1. [blindspot] [medium]
   Insight: "Technical SEO underrepresented"
   Reasoning: "Cluster 1 (keywords, research) dominates but technical optimization concepts missing"
   Action: "Add technical SEO: site speed, schema markup, crawlability"

2. [opportunity] [low]
   Insight: "Expand local SEO cluster"
   Reasoning: "Cluster 3 (local, citations, maps) has low influence (0.047) but high potential for growth"
   Action: "Deepen local SEO: GMB optimization, local link building, review management"
```

---

## Constraints

**AI analyzes ONLY graph structure, not external knowledge:**
- No domain expertise applied
- Insights cite specific clusters/gaps/metrics
- Reasoning based on structural patterns
- Actions derived from graph topology

**Quality depends on:**
- Graph richness (more nodes = better insights)
- Gap quality (clear gaps = clearer insights)
- Cluster coherence (well-defined clusters = better recommendations)

---

## Error Handling

**Graceful degradation:**
- Missing API key → Returns empty insights with `fallback: true`
- API timeout → Returns error message, continues analysis
- Invalid JSON response → Logs warning, returns empty array
- Network errors → Catches exception, returns fallback response

**No impact on core analysis:**
- AI enhancement is optional layer
- Core metrics (modularity, entropy, gaps) unaffected by AI failures
- User always receives base analysis even if AI fails

---

## Limitations

**Current constraints:**
- Single-analysis focus (no cross-session memory)
- No domain-specific templates
- Generic insight types (blindspot/connection/opportunity)
- No confidence scores on insights
- No A/B testing of prompt variations

**Future enhancements (not implemented):**
- Domain-specific prompt templates
- Insight confidence scoring
- Cross-session insight tracking
- Custom focus areas per agent
- Multi-turn AI dialogue for deeper analysis

---

## Related Skills

- **Gap Scoring** - Provides gap metadata for AI reasoning
- **Evolution Tracking** - Provides evolution stage for opportunity insights
- **Question Generation** - Complements AI insights with structured questions

---

**Implementation:** Phase 3 (2025-11-06)
**Test Status:** ✅ Verified operational across @marketing, @seo, @finance
**Documentation:** workspace/docs/Obsidian-v2/daily/2025-11-06-PHASE3-SUMMARY.md