nl-router

Route natural language requests to appropriate skills and workflows.

Triggers

This skill is the meta-router - it processes natural language and routes to other skills. It should be consulted when no explicit skill trigger is matched.

Purpose

This skill interprets natural language requests and routes them to the appropriate skills or workflows by:

• Parsing user intent from natural language
• Matching to available skills and commands
• Handling ambiguous requests with clarification
• Suggesting relevant actions
• Learning from routing patterns

Behavior

When triggered, this skill:

1. Parses user intent:

   • Extract action verbs
   • Identify objects/targets
   • Detect qualifiers and constraints
   • Recognize context from conversation

2. Matches to skills:

   • Search skill trigger patterns
   • Score match confidence
   • Consider context relevance

3. Routes request:

   • High confidence: Route directly
   • Medium confidence: Confirm with user
   • Low confidence: Offer options
   • No match: Suggest alternatives

4. Handles follow-ups:

   • Track routing context
   • Enable corrections
   • Learn from feedback

Routing Patterns

SDLC Workflows

sdlc_patterns:
  phase_transitions:
    patterns:
      - "transition to {phase}"
      - "move to {phase}"
      - "start {phase}"
      - "begin {phase}"
      - "ready for {phase}"
    routes_to: flow-{from}-to-{to}
    extract: [from_phase, to_phase]

  gate_checks:
    patterns:
      - "check gate"
      - "can we transition"
      - "ready for {phase}"
      - "validate {gate}"
      - "gate check"
    routes_to: gate-evaluation
    extract: [gate_name, phase]

  project_status:
    patterns:
      - "where are we"
      - "what's next"
      - "project status"
      - "current phase"
      - "status update"
    routes_to: project-awareness
    action: status_report

  risk_management:
    patterns:
      - "update risks"
      - "risk review"
      - "new risk"
      - "mitigate {risk}"
    routes_to: risk-cycle
    extract: [risk_id, action]

  security_review:
    patterns:
      - "security review"
      - "run security"
      - "threat model"
      - "security scan"
    routes_to: security-assessment
    extract: [scope]

Artifact Operations

artifact_patterns:
  create:
    patterns:
      - "create {artifact}"
      - "generate {artifact}"
      - "new {artifact}"
      - "draft {artifact}"
    routes_to: artifact-orchestration
    extract: [artifact_type]

  review:
    patterns:
      - "review {artifact}"
      - "check {artifact}"
      - "validate {artifact}"
    routes_to: artifact_type_specific_review
    extract: [artifact_type]

  trace:
    patterns:
      - "trace {requirement}"
      - "what implements {id}"
      - "coverage for {id}"
    routes_to: traceability-check
    extract: [requirement_id]

Marketing Workflows

marketing_patterns:
  brand_review:
    patterns:
      - "brand review"
      - "check brand compliance"
      - "is this on-brand"
      - "brand audit"
    routes_to: brand-compliance
    extract: [asset_path]

  approval:
    patterns:
      - "submit for approval"
      - "approval workflow"
      - "get sign-off"
      - "approval status"
    routes_to: approval-workflow
    extract: [asset_id]

  performance:
    patterns:
      - "how are we doing"
      - "marketing report"
      - "performance summary"
      - "campaign results"
    routes_to: performance-digest
    extract: [period, channel]

  competitive:
    patterns:
      - "competitor analysis"
      - "what are competitors doing"
      - "competitive landscape"
    routes_to: competitive-intel
    extract: [competitor_name]

Research & Investigation

research_patterns:
  lookup:
    patterns:
      - "look up {topic}"
      - "what does {thing} do"
      - "how does {thing} work"
      - "find documentation for {topic}"
      - "search for {query}"
      - "check the docs for {topic}"
      - "read about {topic}"
      - "research {topic}"
    routes_to: research-investigation
    extract: [topic, scope]
    rule_activation: research-before-decision

  codebase_exploration:
    patterns:
      - "how is {feature} implemented"
      - "where is {thing} defined"
      - "find {pattern} in the codebase"
      - "what pattern does this project use for {thing}"
      - "show me examples of {pattern}"
    routes_to: codebase-exploration
    extract: [feature, pattern]
    rule_activation: research-before-decision

  error_investigation:
    patterns:
      - "why is {thing} failing"
      - "investigate {error}"
      - "debug {issue}"
      - "what's causing {problem}"
      - "root cause of {error}"
    routes_to: error-diagnosis
    extract: [error, context]
    rule_activation: research-before-decision

Planning & Strategy

planning_patterns:
  approach_planning:
    patterns:
      - "plan how to {task}"
      - "design approach for {task}"
      - "think through {task}"
      - "strategize {task}"
      - "how should I approach {task}"
      - "what's the best way to {task}"
    routes_to: approach-planning
    extract: [task, constraints]

  implementation_planning:
    patterns:
      - "plan the implementation of {feature}"
      - "break down {task}"
      - "outline the steps for {task}"
      - "what do I need to do for {task}"
    routes_to: implementation-planning
    extract: [feature, scope]

  decision_support:
    patterns:
      - "help me decide between {options}"
      - "compare {a} and {b}"
      - "trade-off analysis for {topic}"
      - "which should I choose"
      - "pros and cons of {approach}"
    routes_to: decision-support
    extract: [decision_topic, options]

Clarification & Recovery

clarification_patterns:
  re_read:
    patterns:
      - "re-read my instructions"
      - "that's not what I asked"
      - "I said {correction}"
      - "go back and read what I wrote"
      - "you missed {thing}"
      - "I already told you {thing}"
    routes_to: instruction-reparse
    rule_activation: instruction-comprehension
    priority: high

  confusion:
    patterns:
      - "I'm confused about {topic}"
      - "can you explain {thing}"
      - "what do you mean by {thing}"
      - "I don't understand {thing}"
    routes_to: clarification
    extract: [topic]

  correction:
    patterns:
      - "no, I meant {correction}"
      - "not {wrong}, use {right}"
      - "change that to {correction}"
      - "that's wrong, it should be {correction}"
    routes_to: instruction-correction
    rule_activation: instruction-comprehension
    priority: high
    extract: [correction]

Utility Operations

utility_patterns:
  decision:
    patterns:
      - "help me decide"
      - "compare options"
      - "trade-off analysis"
      - "which should I choose"
    routes_to: decision-support
    extract: [decision_topic]

  test_coverage:
    patterns:
      - "test coverage"
      - "what's not tested"
      - "coverage report"
    routes_to: test-coverage
    extract: [scope]

  incident:
    patterns:
      - "production issue"
      - "system down"
      - "incident"
      - "P0"
      - "SEV1"
    routes_to: incident-triage
    priority: urgent

  config:
    patterns:
      - "validate config"
      - "check setup"
      - "config issues"
    routes_to: config-validator

Intent Classification

Action Verbs

action_verbs:
  create:
    words: [create, generate, new, draft, make, build, write]
    intent: creation

  review:
    words: [review, check, validate, verify, audit, assess]
    intent: validation

  update:
    words: [update, change, modify, edit, revise]
    intent: modification

  delete:
    words: [delete, remove, deprecate, archive]
    intent: removal

  analyze:
    words: [analyze, understand, explain, investigate, explore]
    intent: analysis

  research:
    words: [research, look up, find out, search for, read about, check docs]
    intent: investigation
    rule_activation: research-before-decision

  plan:
    words: [plan, design, strategize, outline, think through, approach]
    intent: planning

  clarify:
    words: [clarify, re-read, explain, what did I, I said, not what I asked]
    intent: clarification
    rule_activation: instruction-comprehension

  transition:
    words: [transition, move, progress, advance, start, begin]
    intent: workflow_progression

  compare:
    words: [compare, contrast, versus, vs, trade-off]
    intent: comparison

Object Mappings

object_mappings:
  artifacts:
    sad: software-architecture-document
    adr: architecture-decision-record
    test_plan: test-plan
    requirements: software-requirements-spec
    threat_model: threat-model

  phases:
    inception: inception
    elaboration: elaboration
    construction: construction
    transition: transition
    production: production

  gates:
    lom: lifecycle-objective-milestone
    abm: architecture-baseline-milestone
    ioc: initial-operational-capability
    prm: product-release-milestone

Confidence Scoring

confidence_levels:
  high:
    threshold: 0.85
    action: route_directly
    example: "create SAD" → artifact-orchestration (SAD)

  medium:
    threshold: 0.60
    action: confirm_before_routing
    example: "review this" → "Did you mean brand review or code review?"

  low:
    threshold: 0.40
    action: offer_options
    example: "help" → "Here are things I can help with..."

  none:
    threshold: 0.0
    action: clarify
    example: "do the thing" → "I'm not sure what you'd like to do. Can you clarify?"

Routing Response Format

Direct Route (High Confidence)

routing_response:
  confidence: high
  matched_skill: artifact-orchestration
  extracted_params:
    artifact_type: sad
  message: "Creating Software Architecture Document..."
  next_action: invoke_skill

Confirmation Route (Medium Confidence)

routing_response:
  confidence: medium
  candidates:
    - skill: brand-compliance
      confidence: 0.72
      reason: "brand" keyword matched
    - skill: code-reviewer
      confidence: 0.65
      reason: "review" action detected
  message: "I found multiple possible actions. Did you mean..."
  next_action: await_clarification

Options Route (Low Confidence)

routing_response:
  confidence: low
  suggestions:
    - category: Documentation
      actions: [create SAD, generate ADR, draft requirements]
    - category: Review
      actions: [brand review, code review, security review]
    - category: Status
      actions: [project status, coverage report, risk review]
  message: "I'm not sure what you'd like to do. Here are some options..."
  next_action: await_selection

Usage Examples

Clear Intent

User: "Generate the architecture document"

Skill routes:
- Intent: create
- Object: architecture document → SAD
- Confidence: 0.95 (high)

Output:
"Routing to artifact-orchestration to generate Software Architecture Document.

Starting SAD generation..."

[Invokes artifact-orchestration with artifact_type=sad]

Ambiguous Intent

User: "Review the landing page"

Skill analyzes:
- Intent: review
- Object: landing page
- Possible skills: brand-compliance, qa-protocol, code-reviewer
- Confidence: 0.65 (medium)

Output:
"I found a few review options for 'landing page':

1. **Brand Review** - Check brand compliance
2. **QA Review** - Check quality and specs
3. **Content Review** - Check copy and messaging

Which would you like?"

Unclear Intent

User: "Help with the project"

Skill analyzes:
- Intent: unclear
- Object: project (generic)
- Confidence: 0.30 (low)

Output:
"I can help with many things! Here are some common actions:

**Project Status**
- Where are we? → Project status
- What's next? → Phase recommendations

**Documentation**
- Create SAD → Architecture document
- Generate ADR → Decision record

**Reviews**
- Security review → Threat assessment
- Brand review → Compliance check

What would you like to do?"

Contextual Routing

User: (After discussing a bug) "Create a ticket for this"

Skill analyzes:
- Context: Bug discussion
- Intent: create
- Object: ticket
- Inference: incident or defect ticket
- Confidence: 0.80 (high with context)

Output:
"Based on our discussion, I'll create an incident ticket for the authentication issue.

Routing to incident-triage..."

Integration

This skill is the central router and integrates with all other skills:

• All SDLC skills
• All MMK skills
• All utility skills
• All workflow commands

Configuration

Custom Patterns

Add custom routing patterns in .aiwg/config/routing.yaml:

custom_patterns:
  - trigger: "standup update"
    routes_to: project-awareness
    action: standup_summary

  - trigger: "weekly report"
    routes_to: performance-digest
    params:
      period: weekly

Priority Overrides

priority_overrides:
  # Urgent patterns always match first
  urgent:
    - "production down"
    - "SEV1"
    - "security breach"

  # Exact matches before fuzzy
  exact_first: true

  # Prefer skill in current context
  context_boost: 0.15

Output Locations

• Routing logs: .aiwg/logs/routing/
• Pattern analytics: .aiwg/analytics/routing-patterns.json

References

• Skill catalog: Available skills from all frameworks
• Command catalog: Available workflow commands
• Translation table: docs/simple-language-translations.md