ADR-039: Canonical Handler Fast-Path Pattern

Status

Approved & Implemented (October 7, 2025)

Related Epics: GREAT-4C, GREAT-4D, GREAT-4E, GREAT-4F Deciders: Chief Architect, Lead Developer Technical Story: Intent classification dual-path architecture

Context and Problem Statement

The intent classification system (ADR-032) routes user queries to appropriate handlers. However, not all queries require the same level of processing complexity or response time. Users expect instant responses for simple queries like “who are you?” or “what day is it?”, while complex operations like “analyze last week’s commits” naturally take longer.

Key questions addressed:

Performance requirements:

Decision Drivers

User Experience

System Performance

Architectural Clarity

Implementation Pragmatism

Considered Options

Option 1: Single Path (All Through Workflows)

Description: Route all intents through workflow orchestration, regardless of complexity.

Pros:

Cons:

Verdict: ❌ Rejected - unacceptable latency for simple queries

Option 2: Single Path (All Canonical)

Description: Implement all intents as fast canonical handlers with hardcoded logic.

Pros:

Cons:

Verdict: ❌ Rejected - insufficient capability for complex operations

Option 3: Dual Path (Canonical + Workflow) ✅

Description: Fast canonical handlers for simple deterministic queries, workflow orchestration for complex operations.

Pros:

Cons:

Verdict: ✅ CHOSEN - optimal tradeoff between speed and capability

Decision Outcome

Chosen option: Dual-path architecture with canonical handlers for simple, deterministic queries and workflow orchestration for complex operations.

Canonical Path (Fast-Path)

Intent Categories: IDENTITY, TEMPORAL, STATUS, PRIORITY, GUIDANCE

Characteristics:

Implementation Location: services/intent/intent_service.py lines 123-131

Example routing code:

# Canonical handler routing (simplified)
if intent.category == IntentCategory.IDENTITY:
    return await self._handle_identity_intent(intent, session_id)
elif intent.category == IntentCategory.TEMPORAL:
    return await self._handle_temporal_intent(intent, session_id)
elif intent.category == IntentCategory.STATUS:
    return await self._handle_status_intent(intent, session_id)
elif intent.category == IntentCategory.PRIORITY:
    return await self._handle_priority_intent(intent, session_id)
elif intent.category == IntentCategory.GUIDANCE:
    return await self._handle_guidance_intent(intent, session_id)

Canonical Handler Examples:

Category Example Query Response Type Speed
IDENTITY “Who are you?” Static text from config ~1ms
TEMPORAL “What day is it?” datetime.now() formatting ~1ms
STATUS “Show standup” PIPER.md section retrieval ~1ms
PRIORITY “What’s my priority?” PIPER.md priority parsing ~1ms
GUIDANCE “How do I…?” Help text lookup ~1ms

Workflow Path (Standard Path)

Intent Categories: EXECUTION, ANALYSIS, SYNTHESIS, STRATEGY, LEARNING, UNKNOWN, QUERY, CONVERSATION

Characteristics:

Implementation: Routes to WorkflowFactory which creates appropriate workflow instances

Workflow Handler Examples:

Category Example Query Operations Required Speed
EXECUTION “Create GitHub issue” LLM classify → GitHub API call → Confirmation 2-3s
ANALYSIS “Analyze commits” Git log retrieval → LLM analysis → Report generation 2-3s
SYNTHESIS “Summarize PRs” GitHub API → LLM summarization → Formatting 2-3s
STRATEGY “Plan sprint” Context gathering → LLM planning → Structured output 2-3s
LEARNING “What patterns exist?” Data extraction → Pattern recognition → Learning update 2-3s

Positive Consequences

User Experience

Performance

Architecture

Validation

Negative Consequences

Complexity

Dependencies

Testing

Mitigation Strategies

For classification accuracy (GREAT-4F):

For developer experience:

For maintenance burden:

Implementation Notes

How Classification Works

Two-stage classification process:

  1. Pre-classifier (Fast Pattern Matching)
    • Checks for canonical category patterns
    • High-confidence keyword/phrase matching
    • Instant routing for recognized patterns
    • Falls back to LLM if uncertain
  2. LLM Classifier (Full Understanding)
    • Natural language understanding
    • Routes to appropriate workflow type
    • Current accuracy: 85-95% (GREAT-4F goal: 95%+)
    • Caching improves performance (84.6% hit rate)

Performance Metrics (from GREAT-4E Validation)

Canonical Path:

Workflow Path:

Overall System:

Decision Criteria for New Intent Categories

Use Canonical Path if ALL of these are true:

Use Workflow Path if ANY of these are true:

When in doubt: Start with workflow path. Can optimize to canonical later if usage patterns warrant.

Examples of Path Selection

Canonical Candidates ✅:

Workflow Candidates ✅:

Codebase Locations

Canonical Handler Implementation:

Workflow Handler Implementation:

Classification:

References

Documentation

Implementation Evidence

Performance Validation

Appendix: Architecture Diagram

User Input (CLI/Web/Slack)
          ↓
    Intent Service
          ↓
    Pre-Classifier
     /           \
    /             \
FAST PATH      UNCERTAIN
 (~1ms)            ↓
   ↓          LLM Classifier
   ↓           /           \
   ↓      CANONICAL      WORKFLOW
   ↓      (re-route)     (2-3s)
   ↓          ↓              ↓
Canonical ←───┘              ↓
Handlers               Workflow Factory
   ↓                         ↓
   ↓                   Orchestration
   ↓                         ↓
   └────────────┬────────────┘
                ↓
            Response

Path Selection Logic:

  1. Pre-classifier attempts pattern match
  2. High confidence → Canonical path (~1ms)
  3. Low confidence → LLM classifier
  4. LLM determines category
  5. Canonical categories → Fast handlers
  6. Workflow categories → Orchestration
  7. QUERY mis-classifications → Smart fallback (GREAT-4F)

Status: ✅ Approved and Implemented Date: October 7, 2025 Next Review: When adding new intent categories or observing classification accuracy issues Maintained By: Lead Developer, Chief Architect