nl-router

Route natural language requests to appropriate skills and workflows.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "route this" → explicit NL routing request
• "what skill handles [X]" → skill discovery

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