meta-router

Original source / Raw SKILL.md

---
name: meta-router
description: |
  Primary intent classifier and entry point for all skill routing. Routes requests through
  the unified 7-router hierarchy based on intent analysis. Triggers on any task requiring
  specialized skills or delegation.
---

# Meta Router

> Entry point for all routing decisions. Classifies intent and delegates to appropriate unified router.

## Unified Router Hierarchy (7 Active)

```
                     META-ROUTER
                    (Entry Point)
                         |
    +----------+---------+---------+----------+
    |          |         |         |          |
    v          v         v         v          v
DELEGATE    TOOLS     BUILD     THINK    CONTEXT
(agents)   (cli/mcp) (dev/docs) (reason) (extract)
                         |
                         v
                    GROUNDING
                   (medical/exam)
```

## Trigger Keywords by Router

```yaml
delegate-router:
  keywords: [complex, multi-step, spawn, delegate, agent, research, explore, ultrawork]
  complexity_triggers: [">0.7", "files>20", "domains>2"]
  route: ~/.claude/skills/routers/delegate-router/SKILL.md

tools-router:
  keywords: [shell, terminal, mcp, lootbox, graph, query, database, cli]
  route: ~/.claude/skills/routers/tools-router/SKILL.md

build-router:
  keywords: [build, implement, code, create, feature, component, docs, readme, deploy]
  absorbs: [development, infrastructure, documentation]
  route: ~/.claude/skills/routers/build-router/SKILL.md

think-router:
  keywords: [analyze, debug, reason, research, investigate, prove, verify, think]
  absorbs: [reasoning, research, analysis]
  route: ~/.claude/skills/routers/think-router/SKILL.md

context-router:
  keywords: [context, lifelog, limitless, pieces, ltm, screenapp, recording]
  route: ~/.claude/skills/routers/context-router/SKILL.md

grounding-router:
  keywords: [saq, viva, medical, exam, anzca, cicm, pex, clinical]
  route: ~/.claude/skills/routers/grounding-router/SKILL.md
```

## Routing Logic

### Weight Distribution

| Factor | Weight | Description |
|--------|--------|-------------|
| Keyword Match | 40% | Scan user intent for trigger keywords |
| Context Analysis | 30% | Current project type, recent operations |
| History Pattern | 20% | Recent skill usage patterns |
| Explicit Request | 10% | User directly names skill/category |

### Decision Flow

```
User Intent
    |
    v
Keyword Extraction --> Category Match --> Load Unified Router
                                              |
                                              v
                                    Router-Specific Logic --> Skill/Agent
```

## Direct Shortcuts (Bypass Routing)

For known skills, bypass routing entirely:

```yaml
# Skill shortcuts
/ultrawork     -> ~/.claude/skills/ultrawork/SKILL.md
/learn         -> ~/.claude/skills/learn/SKILL.md
/lambda        -> ~/.claude/skills/lambda-skill/SKILL.md
/obsidian      -> ~/.claude/skills/obsidian/SKILL.md
/git           -> ~/.claude/skills/git-master/SKILL.md

# Agent shortcuts
oracle         -> oracle agent (complex debugging)
explore        -> explore agent (quick search)
sisyphus       -> sisyphus-junior agent (focused execution)
```

## Complexity Assessment

```python
def assess_complexity(task):
    score = (
        0.30 * files_affected(task) +
        0.25 * domains_involved(task) +
        0.25 * steps_required(task) +
        0.20 * research_needed(task)
    )
    return score

# Routing thresholds
if score > 0.7:
    route_to("delegate-router")  # Complex delegation
elif score > 0.4:
    route_to("think-router")     # Analysis needed
else:
    route_to("build-router")     # Direct execution
```

## Usage

When this router activates:

1. Announce: "Routing to [router] for [reason]"
2. Load the unified router
3. The router further refines to specific skill/agent

## Legacy Router Migration

| Legacy Router | Absorbed By |
|---------------|-------------|
| agents-router | delegate-router |
| skills-router | delegate-router |
| cli-router | tools-router |
| data-router | tools-router |
| development-router | build-router |
| infrastructure-router | build-router |
| documentation-router | build-router |
| reasoning-router | think-router |
| research-router | think-router |
| analysis-router | think-router |

Legacy routers archived in: `~/.claude/db/skills/routers/`

## Integration

**Incoming**: All user requests
**Outgoing**: [delegate-router](../delegate-router/SKILL.md), [tools-router](../tools-router/SKILL.md), [build-router](../build-router/SKILL.md), [think-router](../think-router/SKILL.md), [context-router](../context-router/SKILL.md), [grounding-router](../grounding-router/SKILL.md)
**Related**: [UNIFIED-ARCHITECTURE](../UNIFIED-ARCHITECTURE.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../delegate-router/SKILL.md

```markdown
---
name: delegate-router
description: |
  Unified router for agent delegation and skill routing. Absorbs agents-router + skills-router.
  Triggers on complex tasks, multi-step operations, research, exploration, or specialized skill needs.
---

# Delegate Router (Unified)

**Tier**: unified
**Absorbs**: agents-router, skills-router
**Agent Registry**: `~/.claude/config/agent-registry.yaml` (single source of truth)

> Consolidates: agents-router + skills-router
> Purpose: All delegation to subagents and skills

## Triggers
```yaml
patterns:
  - complex, multi-step, research, explore, ultrawork
  - spawn, delegate, use agent
  - specialized skill needed
  - complexity > 0.7, files > 20, domains > 2

complexity_factors:
  files_affected: 0.30
  domains_involved: 0.25
  steps_required: 0.25
  research_needed: 0.20
```

## Delegation Matrix

**Source**: All delegation decisions now reference `~/.claude/config/agent-registry.yaml`

This provides:
- Power-law tiered agent selection (Tier 1: 80% of work, Tier 2: 15%, Tier 3: 5%)
- Complexity-based model selection (haiku: 0.1-0.3, sonnet: 0.4-0.7, opus: 0.7-1.0)
- External CLI integration (gemini for >100K tokens)
- Single source of truth for all delegation logic

### Quick Reference (from agent-registry.yaml)

**Tier 1 (High-Impact)**: sisyphus-junior, explore, oracle, engineer
**Tier 2 (Specialized)**: librarian, architect, prometheus, momus, metis
**Tier 3 (Utility)**: document-writer, frontend-engineer, multimodal-looker
**External CLI**: gemini (>100K tokens), codex (GPT preference), amp (Claude-specific)

### Skill Discovery
```yaml
lookup_order:
  1. ~/.claude/skills/ (active, 23 skills)
  2. ~/.claude/db/skill-db/ (archived, 67+ skills)
  3. ~/.claude/db/skill-library/ (archived, 48+ skills)
```

## Decision Logic
```yaml
if complexity > 0.7:
  → oracle (analysis) or engineer (implementation)
if files > 20:
  → sisyphus-junior (focused execution)
if domains > 2:
  → architect (system design)
if tokens > 100K:
  → gemini CLI (external, 2M context)
if specialized_skill_match:
  → invoke skill directly
```

## Skill Categories (from skills-router)

| Category | Skills | Triggers |
|:---------|:-------|:---------|
| **Reasoning** | think, reason, AoT, urf, ontolog | analyze, decompose, prove, formal |
| **Research** | deep-research, skill-discovery | research, thorough, citations |
| **Context** | context-orchestrator | lifelog, ltm, personal, pieces |
| **Writing** | dialectical, critique, saq | persuade, evaluate, exam |
| **Development** | terminal, component, mcp-builder | tui, cli, mcp |

## Decision Tree

```
Task Complexity Assessment
    │
    ├── Exploration needed?
    │   ├── Quick search? → Explore (quick)
    │   ├── Pattern finding? → Explore (medium)
    │   └── Deep analysis? → Explore (very thorough)
    │
    ├── Implementation?
    │   ├── From PRD? → engineer
    │   ├── Architecture? → architect
    │   └── Strategy? → prometheus
    │
    ├── Research?
    │   ├── Web/docs? → researcher
    │   ├── Claude Code help? → claude-code-guide
    │   └── Large codebase? → gemini CLI
    │
    ├── Multi-domain?
    │   └── sisyphus-junior or architect
    │
    └── Skill match?
        └── Invoke via Skill tool
```

## Usage Patterns

### Parallel Agents (Independent Tasks)
```yaml
# Spawn together in single message
Task(explore, "find auth files") + Task(librarian, "search auth docs")
```

### Sequential Agents (Dependent Tasks)
```yaml
# Chain results
Task(explore, "find code") → Task(oracle, "debug issue")
```

### Background Execution (Long-Running)
```yaml
Task(sisyphus-junior, task, run_in_background=true)
→ TaskOutput(task_id) to retrieve results
```

## References
- Original agents-router: ~/.claude/db/skills/routers/agents-router/
- Original skills-router: ~/.claude/db/skills/routers/skills-router/

```

### ../tools-router/SKILL.md

```markdown
---
name: tools-router
description: "Unified router for all external tools: CLI binaries, MCP tools via lootbox, and data processing. Consolidates cli-router + tools-router + data-router."
---

# Tools Router (Unified)

**Consolidates**: cli-router + tools-router + data-router
**Purpose**: All external tool execution (CLI, MCP, databases)
**Legacy References**: `~/.claude/db/skills/routers/cli-router/`, `~/.claude/db/skills/routers/data-router/`

## CLI Tools (Local Binaries)

### AI/LLM Agents
| Tool | Binary | Purpose |
|:-----|:-------|:--------|
| gemini | /opt/homebrew/bin/gemini | Google Gemini CLI (2M context) |
| codex | ~/.local/bin/codex | OpenAI GPT models |
| amp | ~/.amp/bin/amp | Anthropic Claude via MCP |

### Context Extraction
| Tool | Binary | Purpose |
|:-----|:-------|:--------|
| research | ~/.local/bin/research | Online documentation |
| pieces | /opt/homebrew/bin/pieces | Local code context, LTM |

### Data Processing
| Tool | Binary | Purpose |
|:-----|:-------|:--------|
| qsv | qsv | Fast CSV processing |
| jq | jq | JSON processing |
| nu | nu | Nushell data pipelines |

### Semantic Search
| Tool | Binary | Purpose |
|:-----|:-------|:--------|
| ck | ck | Semantic code search |
| ast-grep | ast-grep | AST pattern matching |

---

# MCP Tools (Lootbox)

Routes tasks to MCP tools via lootbox code-mode for external service integration.

## MCP Tool Categories

### Knowledge Graph
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| Neo4j | `neo4j` | Graph database operations |
| Neo4j Aura | `neo4j-aura` | Cloud Neo4j |
| Neo4j Memory | `neo4j-memory` | Agent memory graph |
| DeepGraph | `deepgraph` | Code graph analysis |

### Research & Search
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| Perplexity | `perplexity` | AI-powered web search |
| Brave Search | `brave-search` | Web search |
| InfraNodus | `relate` | Graph-based text analysis |
| PageIndex | `pageindex-local` | Web page indexing |

### Methodology & Reasoning
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| Meta-CC | `meta-cc` | Methodology capabilities |
| Distil (AoT) | `distil` | Atom of Thoughts |
| Zen | `zen` | Multi-model reasoning |
| Gepa | `gepa` | Gemini planning |

### Solvers
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| Z3 | `solver-z3` | SMT solving |
| MiniZinc | `solver-minizinc` | Constraint optimization |
| PySAT | `solver-pysat` | SAT solving |
| MaxSAT | `solver-maxsat` | Maximum satisfiability |
| ASP | `solver-asp` | Answer set programming |

### Storage & Memory
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| Filesystem | `filesystem` | File operations |
| MCP Memory | `mcp-memory` | Key-value memory |
| Obsidian Memory | `obsidian-memory` | Obsidian integration |
| TurboVault | `turbovault` | High-performance vault |

### External Services
| Tool | Namespace | Purpose |
|:-----|:----------|:--------|
| GitHub | `github` | GitHub API |
| Zotero | `zotero` | Citation management |
| Gemini | `gemini` | Gemini model access |

## Lootbox Code-Mode

### Configuration
```yaml
server: ws://localhost:9742/ws
ui: http://localhost:9742/ui
config: ~/lootbox.config.json
```

### Local Tools (Always Available)
```typescript
tools.kv.*       // Key-value store
tools.sqlite.*   // SQLite database
tools.memory.*   // In-memory storage
tools.graphql.*  // GraphQL queries
```

### Invocation Patterns

```bash
# List available tools
lootbox tools

# Execute single operation
lootbox exec 'await tools.neo4j.query({ cypher: "MATCH (n) RETURN n LIMIT 5" })'

# Chain operations
lootbox exec '
  const results = await tools.perplexity.search({ query: "Claude Code best practices" });
  await tools.kv.set({ key: "research", value: results });
  return results;
'

# Parallel operations
lootbox exec '
  const [a, b] = await Promise.all([
    tools.neo4j.query({ cypher: "MATCH (n:Skill) RETURN n" }),
    tools.deepgraph.semantic_search({ query: "authentication" })
  ]);
  return { skills: a, code: b };
'
```

## Routing Logic

```
MCP Task Detected
    │
    ├── Graph operations?
    │   ├── Neo4j? → tools.neo4j
    │   ├── Code graph? → tools.deepgraph
    │   └── Text graph? → tools.relate
    │
    ├── Research?
    │   ├── AI search? → tools.perplexity
    │   ├── Web search? → tools.brave-search
    │   └── Page index? → tools.pageindex-local
    │
    ├── Reasoning?
    │   ├── Methodology? → tools.meta-cc
    │   ├── Multi-model? → tools.zen
    │   └── AoT? → tools.distil
    │
    ├── Constraint solving?
    │   ├── SMT? → tools.solver-z3
    │   ├── Optimization? → tools.solver-minizinc
    │   └── SAT? → tools.solver-pysat
    │
    └── Storage?
        ├── Files? → tools.filesystem
        ├── KV? → tools.kv
        └── Memory? → tools.memory
```

## Tool Selection Matrix

| Task Type | Primary Tool | Alternative |
|:----------|:-------------|:------------|
| Graph query | neo4j | deepgraph |
| Web research | perplexity | brave-search |
| Code analysis | deepgraph | relate |
| Constraint solving | solver-z3 | solver-minizinc |
| File operations | filesystem | turbovault |
| Citation | zotero | - |
| Methodology | meta-cc | distil |

## Integration

- **lootbox**: Code-mode execution
- **MCP servers**: External tool providers
- **cli-index**: CLI tool fallback
- **meta-router**: Parent routing

## Quick Reference

```yaml
# Start lootbox server
lootbox server --port 9742

# Check available namespaces
lootbox tools

# Neo4j query
lootbox exec 'await tools.neo4j.query({ cypher: "..." })'

# Perplexity search
lootbox exec 'await tools.perplexity.search({ query: "..." })'

# Chained operations
lootbox exec '
  const data = await tools.X.fetch();
  return tools.Y.process(data);
'
```

```

### ../build-router/SKILL.md

```markdown
---
name: build-router
description: |
  Unified router for development, infrastructure, and documentation tasks.
  Absorbs development-router + infrastructure-router + documentation-router.
---

# Build Router (Unified)

**Tier**: unified
**Absorbs**: development-router + infrastructure-router + documentation-router
**Purpose**: All creation/building tasks (code, configs, docs)

## Triggers
```yaml
patterns:
  - build, implement, create, develop
  - frontend, backend, fullstack, API
  - mcp, server, hook, deploy
  - document, readme, explain, changelog
  - terminal, TUI, CLI interface
```

## Build Domains

### Frontend Development
```yaml
triggers: [UI, UX, component, styling, React, Vue, Svelte]
agent: frontend-engineer
skills:
  - frontend-ui-ux (active)
  - component patterns
  - accessibility (WCAG)
  - responsive design
```

### Backend Development
```yaml
triggers: [API, server, database, authentication]
patterns:
  - RESTful API design
  - GraphQL schemas
  - Database modeling
  - Authentication/authorization
```

### Infrastructure
```yaml
triggers: [MCP, hook, config, deploy, tooling]
skills:
  - mcp-builder (db/skill-db)
  - hook development
  - configuration management
workflows:
  - MCP server: Research → Implement → Review → Evaluate
```

### Documentation
```yaml
triggers: [document, readme, explain, changelog, API docs]
agent: document-writer
patterns:
  - README creation
  - API documentation
  - Code comments
  - Changelogs
```

## Workflow Integration
```yaml
standard_flow:
  1. Analyze requirements
  2. Plan implementation
  3. Build incrementally
  4. Test and validate
  5. Document

sc_commands:
  - sc:implement → Guided implementation
  - sc:build → Build workflow
  - sc:document → Documentation
```

## Build Tool Detection

```yaml
package_managers:
  package.json: pnpm | npm | yarn | bun
  pyproject.toml: uv | poetry | pip
  Cargo.toml: cargo
  go.mod: go

build_commands:
  typescript: "pnpm build" | "npm run build" | "bun build"
  python: "uv run python -m build" | "poetry build"
  rust: "cargo build --release"

test_runners:
  typescript: vitest | jest | playwright
  python: pytest
  rust: cargo test

linting:
  typescript: eslint | prettier | biome
  python: ruff | black | mypy
```

## Decision Tree

```
Build/Create Request
    │
    ├── Frontend?
    │   ├── TUI/terminal? → terminal skill
    │   ├── Component? → frontend-engineer agent
    │   └── Feature → sc:implement
    │
    ├── Backend?
    │   ├── API design? → sc:design
    │   └── Implementation → sc:build
    │
    ├── Infrastructure?
    │   ├── MCP server? → mcp-builder skill
    │   ├── Hooks? → hookify skill
    │   └── Config → component skill
    │
    └── Documentation?
        ├── README → document-writer agent
        ├── API docs → sc:document
        └── Changelog → create-release-note
```

## References
- Original development-router: ~/.claude/db/skills/routers/development-router/
- Original infrastructure-router: ~/.claude/db/skills/routers/infrastructure-router/
- Original documentation-router: ~/.claude/db/skills/routers/documentation-router/

```

### ../think-router/SKILL.md

```markdown
---
name: think-router
description: |
  Unified router for reasoning, research, and analysis tasks.
  Consolidates reasoning-router + research-router + analysis-router.
---

# Think Router (Unified)

**Consolidates**: reasoning-router + research-router + analysis-router
**Purpose**: All analytical/cognitive tasks

## Triggers
```yaml
patterns:
  - analyze, debug, troubleshoot, audit
  - reason, think, prove, verify
  - research, investigate, deep-dive, study
  - security, performance, optimization
```

## Thinking Modes

### Analysis Mode
```yaml
triggers: [analyze, debug, troubleshoot, audit, security, performance]
agent: oracle
workflows:
  - Root cause analysis
  - Security audit
  - Performance profiling
  - Code review

sc_commands:
  - sc:analyze → Codebase analysis
  - sc:troubleshoot → Systematic debugging
```

### Research Mode
```yaml
triggers: [research, investigate, deep-dive, study, learn]
agent: researcher
skills:
  - deep-research (db/skill-db) - 7-phase methodology
  - codebase-researcher (db/skill-db) - Systematic codebase analysis
workflows:
  - Classify → Scope → Hypothesize → Plan → Query → Triangulate → Synthesize
```

### Reasoning Mode
```yaml
triggers: [reason, think, prove, verify, logic]
skills:
  - hierarchical-reasoning (db/skill-db) - Strategic/Tactical/Operational
  - think (db/skill-db) - ThoughtBox + mental models
  - reason (db/skill-db) - Parse → Branch → Reduce → Ground → Emit

patterns:
  - Forward thinking (goal → actions)
  - Backward thinking (goal ← requirements)
  - Branching (explore alternatives)
  - First principles (fundamental truths)
  - Meta-reflection (reasoning about reasoning)
```

## Integration with Skills
```yaml
unified_skills:
  deep-research:
    core: 7-phase research methodology
    extensions: codebase analysis, web extraction

  hierarchical-reasoning:
    core: 3-level cognitive architecture
    extensions: ThoughtBox patterns, mental models
```

## References
- Original reasoning-router: ~/.claude/db/skills/routers/reasoning-router/
- Original research-router: ~/.claude/db/skills/routers/research-router/
- Original analysis-router: ~/.claude/db/skills/routers/analysis-router/

```

### ../context-router/SKILL.md

```markdown
---
name: context-router
description: |
  Routes context extraction requests to appropriate CLI tools. Triggers on /context,
  /limitless, /research, /pieces, or detected context needs from intent hook.
  Supports single, parallel, and augmented extraction modes.
---

# Context Router

Routes external context extraction to the three-CLI system.

**Trigger Keywords**: context, lifelog, research, ltm, recall, lookup, pieces, limitless, pendant, documentation

## Trigger Conditions

Activate when:
- Explicit commands: `/context`, `/limitless`, `/research`, `/pieces`
- Intent hook signals context need (balanced detection)
- User asks about past conversations, technical docs, or code history

## Source Categories

| Source | CLI | Triggers | Data Type |
|:-------|:----|:---------|:----------|
| **Personal** | limitless | lifelog, pendant, daily, personal, meeting | Transcripts, chats |
| **Research** | research | fact-check, docs, academic, verify, sdk | Citations, documentation |
| **Local** | pieces | ltm, saved, snippets, my code, history | Code, snippets |

## Routing Decision Tree

```
Request Received
    │
    ├── Explicit Command?
    │   ├── /context → Parallel (all sources)
    │   ├── /limitless → Single (limitless)
    │   ├── /research → Single (research)
    │   └── /pieces → Single (pieces)
    │
    ├── Hook Signal Present?
    │   ├── need_limitless=true → Route to limitless
    │   ├── need_research=true → Route to research
    │   ├── need_pieces=true → Route to pieces
    │   └── Multiple → Parallel mode
    │
    └── No Signal
        └── Skip (no context needed)
```

## Mode Selection

| Mode | Trigger | Process |
|------|---------|---------|
| **Single** | Clear single-source intent | Route to one CLI |
| **Parallel** | `/context` or multi-domain | Spawn all relevant CLIs |
| **Augmented** | With deep-research | Pre-enrich Phase 0 |

## CLI Commands

### Limitless (Personal)
```bash
limitless lifelogs search "query" --limit 10 --format json
limitless workflow daily YYYY-MM-DD --format json
limitless workflow recent --hours 24 --format json
```

### Research (Online)
```bash
research docs -t "query" -k "framework" --format json
research fact-check -t "claim" --format json
research pex-grounding -t "medical query" --format json
```

### Pieces (Local)
```bash
pieces ask "query" --ltm
pieces search --mode ncs "pattern"
```

## Integration

- **Skill**: `skill-db/context-orchestrator/SKILL.md`
- **Rules**: `rules/context/*.md`
- **Subagents**: `skill-db/context-orchestrator/agents/*.md`
- **Commands**: `skill-db/context-orchestrator/commands/*.md`
- **Also listed in**: `skills/routers/skills-router/SKILL.md` (Context Skills category)
- **Hooks**: `hooks/context-intent-detector.ts`, `hooks/session-context-primer.sh`

```

### ../grounding-router/SKILL.md

```markdown
---
name: grounding-router
description: |
  Routes medical education grounding requests through atomic primitive composition.
  Four primitives (Σ Source, Τ Textbook, Δ Dialectical, Ρ Response) combine via
  operators (∘ ⊗ * |) for SAQ/VIVA/Academic response generation.
  Integrates: limitless, research, pieces, pdf-search, pdf-brain CLIs.
---

# Grounding Router

**Version**: 3.0.0
**Architecture**: atomic-permutation-router
**Trigger Keywords**: grounding, saq, viva, textbook, pex, medical, citations, synthesis, sc:grounding

**Progressive Loading**:
- Level 0: Frontmatter (~100 tokens) - trigger detection only
- Level 1: Core SKILL.md (~2500 tokens) - primitives + routing
- Level 2: references/*.md - on-demand deep specifications
- Level 3: scripts/*.py - execute without loading context

**Integrations**:
- Skills: dialectical, critique, mega, textbook-grounding, saq, qp
- CLIs: limitless, research, pieces, pdf-search, pdf-brain, pex
- Commands: sc:grounding
- Routers: context-router

> **λΩ.τ**: Query(ο) → Atomic-Composition(λ) → Grounded-Response(τ)

Routes grounding requests through minimal atomic primitives for maximal emergent function.

## Trigger Conditions

Activate when:
- Explicit: `/grounding`, `/saq`, `/viva`, `sc:grounding`
- Implicit: SAQ, VIVA, medical exam, textbook citations, PEX sources
- Hook signal: `need_grounding=true` from intent detection

## Routing Decision Tree

```
Request Received
    │
    ├── Mode Detection
    │   ├── "SAQ" or ~200 words → SAQ Mode
    │   ├── "VIVA" or examiner → VIVA Mode
    │   ├── "academic" or paper → Academic Mode
    │   └── Default → SAQ Mode
    │
    ├── Composition Selection
    │   ├── SAQ: (Σ ⊗ Τ) ∘ Δ ∘ Ρₛ
    │   ├── VIVA: Σ* ∘ (Τ ⊗ Δ) ∘ Ρᵥ*
    │   └── Academic: Σ* ∘ Τ* ∘ Δ* ∘ Ρₐ
    │
    └── Pipeline Execution
        ├── G₀: Preflight (CLI health)
        ├── Σ: Source extraction
        ├── Τ: Textbook grounding
        ├── Δ: Dialectical synthesis
        ├── G₄: Hallucination check
        └── Ρ: Response generation
```

## The Four Atomic Primitives

| Symbol | Name | λο.τ Form | CLI Sources |
|:-------|:-----|:----------|:------------|
| **Σ** | SOURCE | Context(ο) → Extraction(λ) → Evidence(τ) | limitless, pieces, pdf-search, research |
| **Τ** | TEXTBOOK | Evidence(ο) → Grounding(λ) → Citation(τ) | pdf-search, pdf-brain |
| **Δ** | DIALECTICAL | Claims(ο) → Synthesis(λ) → Universal(τ) | Thesis→Antithesis→Synthesis |
| **Ρ** | RESPONSE | Synthesis(ο) → Formatting(λ) → Output(τ) | SAQ/VIVA/Academic modes |

## Composition Operators

| Operator | Notation | Function | Pattern |
|:---------|:---------|:---------|:--------|
| Sequential | ∘ | Apply in order | `Σ ∘ Τ` (extract then ground) |
| Parallel | ⊗ | Concurrent | `Σₚ ⊗ Σₜ` (parallel sources) |
| Recursive | * | Until convergence | `Δ*` (resolve all antitheses) |
| Conditional | \| | Activate on condition | `Σ \| has_cache` |

## Source Sub-Primitives (Σ)

| Symbol | CLI | Triggers | Output |
|:-------|:----|:---------|:-------|
| Σₚ | limitless | personal, lifelog, recall | personal_context[] |
| Σₗ | pieces | ltm, snippet, history | local_context[] |
| Σₜ | pdf-search | textbook, book, page | textbook_chunks[] |
| Σₐ | research | pex, guidelines, evidence | authoritative_sources[] |
| Σₚₑₓ | pex | exam, lo, saq, curriculum | exam_context[] |

### CLI Commands

```bash
# Σₚ — Personal Context
limitless lifelogs search "{topic}" --limit 10 --json

# Σₗ — Local Context
echo "" | pieces ask "{topic}" --ltm

# Σₜ — Textbook Context
pdf-search "{topic}" --limit 10 --tags {tags}
pdf-brain search "{topic}" --limit 10

# Σₐ — Authoritative Context
research pex-grounding -t "{topic}" --specialty {specialty} --format json

# Σₚₑₓ — PEX Exam Context
pex search "{topic}" --limit 10
pex prereq "LO:{id}" --model fast
pex path "{topic}" --max 10
```

## Mode Compositions

### SAQ Mode: `(Σ ⊗ Τ) ∘ Δ ∘ Ρₛ`

```
Parallel source + textbook → Sequential synthesis → SAQ output
Word count: 180-220 | Citations: 5-10 | Tables: max 1
```

### VIVA Mode: `Σ* ∘ (Τ ⊗ Δ) ∘ Ρᵥ*`

```
Recursive sources → Parallel ground+synthesize → Recursive expand
Word count: 500-800 | Citations: 15-25 | Examiner probes: 3-5
```

### Academic Mode: `Σ* ∘ Τ* ∘ Δ* ∘ Ρₐ`

```
All recursive → Maximum depth → Full scholarly
Word count: 1000-2000 | Citations: 30-50 | Full bibliography
```

## Quality Gates

| Gate | Check | Pass Criteria |
|:-----|:------|:--------------|
| G₀ | Preflight | ≥3/5 CLIs available |
| G₁ | Sources | ≥2 sources, ≥2 types |
| G₂ | Textbook | ≥50% claims grounded |
| G₃ | Synthesis | All theses subsumed |
| G₄ | Hallucination | <20% flagged claims |
| G₅ | Output | Word count compliant |

## Confidence Calculation

```python
confidence = (
    0.30 * source_authority +
    0.25 * textbook_coverage +
    0.20 * synthesis_parsimony +
    0.15 * citation_density +
    0.10 * hallucination_pass_rate
)
```

| Confidence | Action |
|:-----------|:-------|
| ≥ 0.85 | Emit response |
| 0.70-0.84 | Warn, emit |
| 0.50-0.69 | Load references/, retry |
| < 0.50 | Execute scripts/, escalate |

## Progressive Loading Protocol

### Level 0: Trigger (Always Active)
- Frontmatter triggers in hook
- ~100 tokens loaded

### Level 1: Core (On Trigger Match)
- This SKILL.md body
- Routing + primitive specs

### Level 2: References (On Demand)
Load when confidence < 0.7 or customization needed:
- `references/atomic-primitives.md` — Full sub-primitive specs
- `references/composition-patterns.md` — Advanced compositions
- `references/quality-gates.md` — Detailed validation
- `references/cli-integration.md` — CLI command patterns

### Level 3: Scripts (Execute Only)
Invoke without loading context:
- `scripts/preflight.py --format json` — CLI health
- `scripts/extract.py "{query}"` — Parallel extraction
- `scripts/validate.py -r response.md` — Hallucination check

## Integration Points

### Context Router Handoff
```yaml
when: Σ primitives activated
action: Delegate to context-router for CLI orchestration
return: Aggregated sources to Τ primitive
```

### Skill Integration
```yaml
dialectical: Δ uses dialectical.atomic-composition
critique: G₄ uses critique.multi-lens
saq: Ρₛ uses saq.template
mega: Δ* escalates to mega when depth > 3
```

### Command Integration
```yaml
sc:grounding:
  invokes: grounding-router with mode detection
  flags: --mode, --sources, --specialty
```

## Example Invocations

### Basic SAQ
```
/grounding "Describe labetalol pharmacology" --mode=saq

Composition: (Σₗ ⊗ Σₜ ⊗ Σₐ) ∘ Δ ∘ Ρₛ
Output: 195-word SAQ with 7 citations
Confidence: 0.89
```

### Extended VIVA
```
/grounding "Pre-eclampsia management" --mode=viva --sources=all

Composition: Σ* ∘ (Τ ⊗ Δ*) ∘ Ρᵥ*
Output: 650-word VIVA with 22 citations + 5 probes
Confidence: 0.92
```

## Anti-Patterns

| Pattern | Why Harmful | Fix |
|:--------|:------------|:----|
| Σ without Τ | Ungrounded claims | Always include Τ |
| Δ without Σₜ | No textbook basis | Require textbook source |
| Ρ without Δ | No synthesis | Dialectical before response |
| Skip G₄ | Hallucination risk | Always validate |

---

**Recursion**: `grounding-router(grounding-router)` → meta-grounding for skill improvement.

```