Semantic Translation

What this skill does

# Semantic Translation & Ontological Mapping

## Purpose

Prevent miscommunication, assumptions, and hallucinations by translating ambiguous user terminology into precise technical concepts across multiple domains. Act as a semantic bridge between human natural language and technical specificity, mapping concepts across Autogen, Langroid, MCP, UTCP, FastAPI, Git/Gitflow, SRE, and Memory Graphs ecosystems.

## Supported Domains

This skill provides semantic translation and disambiguation across 8 technical domains:

1. **Autogen** - Multi-agent orchestration (ConversableAgent, AssistantAgent, UserProxyAgent, GroupChat)
2. **Langroid** - Agent framework (ChatAgent, ToolAgent, Task orchestration)
3. **MCP (Model Context Protocol)** - Server types (SSE, stdio, HTTP, WebSocket), tools, resources, prompts, sampling
4. **UTCP (Universal Tool Calling Protocol)** - Framework-agnostic tool schemas, adapters, universal tool definitions
5. **FastAPI** - Python web framework (path operations, dependency injection with Depends(), Pydantic models, APIRouter)
6. **Git/Gitflow** - Version control workflows (feature/release/hotfix branches, merge strategies, collaboration patterns)
7. **SRE (Site Reliability Engineering)** - Observability pillars (logs/metrics/traces), SLO/SLI/SLA, incident management
8. **Memory Graphs** - Knowledge graph structures (entities, relationships, embeddings, episodic/semantic/procedural memory)

## The Core Problem

Users frequently encounter the "abyss" between natural language intent and technical precision:

- **Vague terminology**: "make it talk", "we need an api", "make it work"
- **Unclear scope**: "check for gaps", "make it portable"
- **Meta-questions**: "am I making sense?", "does this make sense?"
- **Domain confusion**: Mixing business and technical terminology
- **Invented terms**: User-created words not in domain vocabulary

Without intervention, these ambiguities lead to:
- AI assumptions and hallucinations
- Misaligned implementations
- Wasted development time
- Project failures from misunderstood requirements

## When to Use This Skill

Trigger semantic validation when detecting:

1. **Ambiguous Action Verbs**
   - "make it [X]" → Multiple technical interpretations possible
   - "do the thing" → No clear referent
   - "fix it" → Unclear what or how

2. **Meta-Questions (User Seeking Validation)**
   - "am I making sense?" → User uncertain about their explanation
   - "does this make sense?" → User seeking confirmation
   - "is this right?" → User wants validation
   - "non-technical user" → User self-identifies as potentially ambiguous

3. **Domain-Crossing Language**
   - Mixing business and technical terms
   - Unclear which framework/library intended
   - Generic terms with multiple technical meanings

4. **Unclear References**
   - "that", "the previous thing", "like before"
   - References without clear antecedents

5. **Scope Ambiguity**
   - "portable" → Docker? Cross-platform? Vendoring? Executable?
   - "api" → HTTP server? API client? API design? Internal interface?
   - "gaps" → Code coverage? Documentation? Features? Security?

## Core Workflow

### Step 1: Detect Ambiguity

Analyze the user's message for ambiguity signals. Use pattern matching from `scripts/detect-ambiguity.py` or manual analysis.

**High-confidence triggers (always validate):**
- Explicit meta-questions: "am I making sense?"
- Vague action verbs with unclear objects: "make it talk"
- Domain confusion: mixing incompatible terminology
- User self-identification: "I'm a non-technical user"

**Moderate-confidence triggers (validate if >80% confidence):**
- Generic technical terms: "api", "agent", "portable"
- Unclear scope: "check for gaps", "add validation"
- Invented terminology: words not in domain vocabulary

### Step 2: Query Knowledge Sources (In Order)

Query knowledge sources in this specific order for efficiency:

**1. Static Domain Knowledge (First - Fastest)**
- Query `knowledge/ambiguous-terms.json` for known ambiguous phrases
- Check `knowledge/technical-mappings.json` for domain-specific translations
- Review `knowledge/ontology-graph.json` for conceptual relationships

**2. External Documentation (Second - Authoritative)**
- Query official documentation (Autogen, Langroid, etc.) via available tools
- Use WebFetch, context7, or deepwiki MCP for current API references
- Validate against authoritative sources when static knowledge insufficient

**3. Codebase Validation (Third - Context-Specific)**
- Use LSP to query symbol definitions in user's project
- Use Grep to search for actual usage patterns
- Identify project-specific terminology and conventions

### Step 3: Translate Ambiguous → Precise

Map ambiguous terminology to precise technical concepts using domain knowledge.

**Translation process:**
1. Identify all possible technical interpretations
2. Rank by confidence score (from knowledge files)
3. Consider user's context (recent conversation, project domain)
4. Present options if multiple interpretations viable

**Example translation:**
```
Ambiguous: "make it talk"
Domain: Autogen
Possible translations:
- ConversableAgent.send() (confidence: 0.8, context: single message)
- register ConversableAgent (confidence: 0.7, context: enable conversation)
- GroupChat setup (confidence: 0.5, context: multi-agent conversation)
```

### Step 4: Engage Conversational Clarification

**Never assume.** Always verify understanding with the user.

Present options conversationally:
```
I notice "[ambiguous term]" could mean different things:

1. [Precise interpretation 1] - [Brief context]
2. [Precise interpretation 2] - [Brief context]
3. [Precise interpretation 3] - [Brief context]

[Ask clarifying question based on context]
```

**Tone guidelines:**
- Conversational, not clinical
- Helpful, not pedantic
- Transparent about uncertainty
- Frame as collaboration, not correction

**Wait for confirmation** before proceeding with implementation.

## Decision Trees

### Primary Decision Tree

```
User message received
├── Contains meta-question? ("am I making sense?")
│   ├── Yes → HIGH confidence, validate immediately
│   └── No → Continue analysis
├── Contains ambiguous action verb? ("make it talk")
│   ├── Yes → Check domain context
│   │   ├── Clear domain → Query knowledge, translate
│   │   └── Unclear domain → Ask which framework/library
│   └── No → Continue analysis
├── Contains vague scope? ("check for gaps", "make it portable")
│   ├── Yes → Query knowledge for common interpretations
│   │   ├── Multiple viable → Present options
│   │   └── One clear match → Confirm with user
│   └── No → Continue analysis
├── Contains domain-crossing language?
│   ├── Yes → Identify conflicting domains, ask clarification
│   └── No → Proceed normally (low ambiguity)
```

### Clarification Decision Tree

```
Ambiguity detected
├── Confidence score > 80%?
│   ├── Yes → Trigger validation
│   └── No → Monitor, don't interrupt
├── Query knowledge sources (static → external → codebase)
├── Translation mappings found?
│   ├── Yes, single mapping → Confirm with user
│   ├── Yes, multiple mappings → Present options
│   └── No mappings found → Ask open-ended clarification
└── User confirms → Proceed with precise terminology
```

## Domain Quick Reference

Key ambiguous terms across all 8 supported domains with precise translations:

### Autogen Domain

**"make it talk"** → ConversableAgent.send() (single message) vs initiate_chat() (conversation) vs GroupChat setup (multi-agent)
**"agent"** → ConversableAgent (base) vs AssistantAgent (LLM-powered) vs UserProxyAgent (human proxy)

### Langroid Domain

**"agent"** → ChatAgent (conversation) vs ToolAgent (function-calling)
**"task"** → Langroid Task object (orchestration) vs general task concept

### MCP Domain

**"mcp server"** → SSE server (web-based) vs stdio server (process-based) vs HTTP server vs WebSocket server
**"resource"** → MCP resource (data/content exposed by server) vs system resource (CPU/memory)
**