ADR-191: Intent Classification System

Status

Accepted - December 15, 2025

Context

CODITECT needs a way to understand user intent from natural language queries and route them to the appropriate agents, commands, or workflows. Without intent classification, users must know exact command syntax and agent names.

Problem Statement

Barrier to Entry: Users must learn specific command syntax (/agent senior-architect "design system")
Agent Discovery: Users don't know which of 776 agents is best for their task
Workflow Routing: Complex tasks require multiple agents in sequence
Context Awareness: Same query may require different routing based on project context

Requirements

Classify natural language into actionable intents
Route to appropriate CODITECT components (agents, commands, skills)
Support multi-intent queries (e.g., "review code and deploy to staging")
Maintain context awareness across session
Integrate with MoE verification layer

Decision

Implement a Multi-Stage Intent Classification System with three classification layers:

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    INTENT CLASSIFICATION SYSTEM                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   User Query: "Help me debug the authentication error"              │
│         │                                                            │
│         ▼                                                            │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │              LAYER 1: COARSE CLASSIFICATION                  │   │
│   │  Intent Categories:                                          │   │
│   │  • development (code, debug, test)                          │   │
│   │  • infrastructure (deploy, scale, monitor)                  │   │
│   │  • documentation (write, update, review)                    │   │
│   │  • analysis (research, analyze, compare)                    │   │
│   │  • management (plan, track, report)                         │   │
│   │  • meta (help, list, configure)                             │   │
│   └───────────────────────┬─────────────────────────────────────┘   │
│                           │                                          │
│                           ▼                                          │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │              LAYER 2: FINE CLASSIFICATION                    │   │
│   │  Sub-intents for "development":                              │   │
│   │  • code_review, code_write, code_refactor                   │   │
│   │  • debug_error, debug_performance                           │   │
│   │  • test_write, test_run, test_fix                           │   │
│   │                                                              │   │
│   │  Matched: debug_error                                        │   │
│   └───────────────────────┬─────────────────────────────────────┘   │
│                           │                                          │
│                           ▼                                          │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │              LAYER 3: COMPONENT ROUTING                      │   │
│   │  Candidate Agents:                                           │   │
│   │  1. debugging-specialist (95% match)                        │   │
│   │  2. backend-development (82% match)                         │   │
│   │  3. senior-architect (71% match)                            │   │
│   │                                                              │   │
│   │  Selected: debugging-specialist                              │   │
│   │  Fallback: backend-development                               │   │
│   └───────────────────────┬─────────────────────────────────────┘   │
│                           │                                          │
│                           ▼                                          │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    MoE VERIFICATION                          │   │
│   │  Route through Constitutional Court if:                      │   │
│   │  • Confidence < 0.8                                         │   │
│   │  • Multi-intent detected                                    │   │
│   │  • Security-sensitive operation                             │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Intent Taxonomy

Level 1: Coarse Categories

Category	Keywords	Primary Track
`development`	code, debug, test, fix, implement	A, B
`infrastructure`	deploy, scale, monitor, configure	C
`documentation`	document, write, explain, readme	F
`security`	audit, secure, vulnerability, compliance	D
`analysis`	analyze, research, compare, evaluate	H
`management`	plan, track, report, status	J
`meta`	help, list, configure, settings	-

Level 2: Fine-Grained Intents

development:
  - code_write: "implement", "create", "add", "build"
  - code_review: "review", "check", "audit code"
  - code_refactor: "refactor", "clean up", "optimize"
  - debug_error: "debug", "fix error", "troubleshoot"
  - debug_performance: "slow", "performance", "profile"
  - test_write: "write test", "add test", "test coverage"
  - test_run: "run tests", "execute tests"
  - test_fix: "fix test", "flaky test"

infrastructure:
  - deploy: "deploy", "release", "publish"
  - scale: "scale", "autoscale", "resize"
  - monitor: "monitor", "alert", "dashboard"
  - configure: "configure", "setup", "initialize"

Classification Algorithm

from typing import Tuple, List, Dict
from dataclasses import dataclass

@dataclass
class IntentResult:
    coarse_category: str
    fine_intent: str
    confidence: float
    candidate_agents: List[Tuple[str, float]]
    requires_moe: bool
    extracted_entities: Dict[str, str]

def classify_intent(query: str, context: dict) -> IntentResult:
    """
    Classify user query into actionable intent.

    Uses three-stage classification:
    1. Coarse category detection (rule-based + embedding)
    2. Fine intent classification (embedding similarity)
    3. Component routing (agent matching)
    """

    # Stage 1: Coarse classification
    coarse_category, coarse_confidence = classify_coarse(query)

    # Stage 2: Fine classification
    fine_intent, fine_confidence = classify_fine(query, coarse_category)

    # Stage 3: Agent routing
    candidate_agents = route_to_agents(fine_intent, context)

    # Extract entities (file names, error messages, etc.)
    entities = extract_entities(query)

    # Determine if MoE verification needed
    requires_moe = (
        fine_confidence < 0.8 or
        is_multi_intent(query) or
        is_security_sensitive(fine_intent)
    )

    return IntentResult(
        coarse_category=coarse_category,
        fine_intent=fine_intent,
        confidence=fine_confidence,
        candidate_agents=candidate_agents,
        requires_moe=requires_moe,
        extracted_entities=entities
    )

Storage Integration (ADR-118 Compliant)

Intent classification results are stored for learning and analytics:

# Store in sessions.db (Tier 3 - regenerable)
from scripts.core.paths import get_sessions_db_path

def store_intent_classification(result: IntentResult, session_id: str):
    """Store intent classification for analytics and learning."""
    conn = sqlite3.connect(get_sessions_db_path())
    conn.execute("""
        INSERT INTO intent_classifications
        (session_id, query, coarse_category, fine_intent,
         confidence, selected_agent, timestamp)
        VALUES (?, ?, ?, ?, ?, ?, ?)
    """, (session_id, query, result.coarse_category,
          result.fine_intent, result.confidence,
          result.candidate_agents[0][0] if result.candidate_agents else None,
          datetime.utcnow().isoformat()))
    conn.commit()

Entity Extraction

The system extracts structured entities from queries:

Entity Type	Pattern	Example
`file_path`	`/path/to/file`, `*.py`	"Fix error in src/auth.py"
`error_message`	Quoted text, stack trace	"Getting 'undefined is not a function'"
`task_id`	`X.N.N.N` format	"Work on task A.3.1.2"
`agent_name`	Known agent names	"Use senior-architect"
`technology`	Language/framework names	"In TypeScript React"

Implementation

Files

File	Purpose
`scripts/intent_classifier.py`	Main classification logic
`config/intent-taxonomy.yaml`	Intent hierarchy definition
`config/agent-intent-mapping.json`	Agent to intent mapping
`skills/intent-classification/SKILL.md`	Skill for manual classification

Command Integration

# Implicit (via /orient or natural language)
"Help me debug this authentication error"
# → Classifies as: development/debug_error
# → Routes to: debugging-specialist

# Explicit override
/intent classify "deploy the new version"
# → Shows classification details without executing

# Batch classification
/intent analyze session
# → Analyzes all queries in session, shows patterns

Consequences

Positive

Natural Language Interface: Users can express intent naturally
Agent Discovery: System finds best agent without user knowing catalog
Context Awareness: Classification considers project context
Learning: Classification improves over time via feedback

Negative

Latency: Classification adds ~50-100ms per query
Ambiguity: Some queries have multiple valid interpretations
Maintenance: Intent taxonomy needs regular updates

Risks

Risk	Mitigation
Misclassification	MoE verification for low confidence
Outdated taxonomy	Quarterly taxonomy review cycle
Context leakage	Session-scoped context only

Author: CODITECT Team Approved: December 15, 2025 Migration: Migrated from cloud-infra per ADR-150 on 2026-02-03

Status​

Context​

Problem Statement​

Requirements​

Decision​

Architecture​

Intent Taxonomy​

Classification Algorithm​

Storage Integration (ADR-118 Compliant)​

Entity Extraction​

Implementation​

Files​

Command Integration​

Consequences​

Positive​

Negative​

Risks​

Related Documents​