gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator/skills/orchestration-qa/routing-validation.md

Routing Validation

Purpose: Detect violations of mandatory Skill usage patterns (Skills vs Direct tools vs Subagents).

When: After ANY workflow completes

Applies To: All Skills and Subagents

Token Cost: ~300-500 tokens

Critical Routing Rules

Rule 1: Status Changes MUST Use Status Progression Skill

Violation: Calling manage_container(operation="setStatus") directly

Expected: Use Status Progression Skill for ALL status changes

Why Critical: Prerequisite validation (summary length, dependencies, task completion) required

Detection:

if (statusChanged && !usedStatusProgressionSkill) {
  return {
    severity: "CRITICAL",
    violation: "Status change bypassed mandatory Status Progression Skill",
    impact: "Prerequisites may not have been validated",
    expected: "Use Status Progression Skill for status changes"
  }
}

Rule 2: Feature Creation MUST Use Feature Orchestration Skill

Violation: Calling manage_container(operation="create", containerType="feature") directly

Expected: Use Feature Orchestration Skill for feature creation

Why Critical: Complexity assessment and template discovery required

Detection:

if (featureCreated && !usedFeatureOrchestrationSkill) {
  return {
    severity: "CRITICAL",
    violation: "Feature creation bypassed mandatory Feature Orchestration Skill",
    impact: "Complexity not assessed, templates may be missed",
    expected: "Use Feature Orchestration Skill for feature creation"
  }
}

Rule 3: Task Execution SHOULD Use Task Orchestration Skill

Violation: Launching specialists directly without checking dependencies/parallel opportunities

Expected: Use Task Orchestration Skill for batch execution

Why Important: Dependency analysis and parallelization optimization

Detection:

if (multipleTasksLaunched && !usedTaskOrchestrationSkill) {
  return {
    severity: "WARN",
    violation: "Multiple tasks launched without Task Orchestration Skill",
    impact: "May miss parallel opportunities or dependency conflicts",
    expected: "Use Task Orchestration Skill for batch execution"
  }
}

Rule 4: Implementation Specialists MUST Use Status Progression for Completion

Violation: Specialist calls manage_container(operation="setStatus") directly

Expected: Specialist uses Status Progression Skill to mark complete

Why Critical: Prerequisite validation (summary, Files Changed section, tests)

Detection:

if (implementationSpecialist && taskCompleted && !usedStatusProgressionSkill) {
  return {
    severity: "CRITICAL",
    violation: `${specialistName} marked task complete without Status Progression Skill`,
    impact: "Summary/Files Changed/test validation may have been skipped",
    expected: "Use Status Progression Skill in Step 8 of specialist lifecycle"
  }
}

Validation Workflow

Step 1: Identify Workflow Type

workflowType = identifyWorkflow(entityType, userInput, output)
// Returns: "status-change", "feature-creation", "task-execution", "implementation"

Step 2: Check Mandatory Skill Usage

mandatorySkills = {
  "status-change": "status-progression",
  "feature-creation": "feature-orchestration",
  "task-execution": "task-orchestration",  // WARN level
  "feature-completion": "feature-orchestration"
}

requiredSkill = mandatorySkills[workflowType]

Step 3: Detect Skill Bypass

// Check if required Skill was used
skillUsed = checkSkillUsage(output, requiredSkill)

if (!skillUsed && requiredSkill) {
  severity = (workflowType == "task-execution") ? "WARN" : "CRITICAL"

  violation = {
    workflowType: workflowType,
    requiredSkill: requiredSkill,
    actualApproach: detectActualApproach(output),
    severity: severity,
    impact: describeImpact(requiredSkill)
  }
}

Step 4: Verify Specialist Lifecycle Adherence

For Implementation Specialists (Backend, Frontend, Database, Test, Technical Writer):

if (category == "SUBAGENT" && isImplementationSpecialist(entityType)) {
  lifecycle = {
    step8Expected: "Use Status Progression Skill to mark complete",
    step8Actual: detectStep8Approach(output),
    compliant: false
  }

  // Check if Status Progression Skill was mentioned
  if (mentions(output, "Status Progression") || mentions(output, "status-progression")) {
    lifecycle.compliant = true
  } else if (taskStatusChanged) {
    violation = {
      severity: "CRITICAL",
      specialist: entityType,
      step: "Step 8",
      issue: "Marked task complete without Status Progression Skill",
      impact: "Prerequisite validation (summary, Files Changed, tests) may be incomplete",
      expected: "Use Status Progression Skill for completion"
    }
  }
}

Violation Severity Levels

CRITICAL (Immediate Alert)

• Status change without Status Progression Skill
• Feature creation without Feature Orchestration Skill
• Implementation specialist completion without Status Progression Skill
• Action: Report immediately, add to TodoWrite, suggest correction

WARN (Log for Review)

• Task execution without Task Orchestration Skill (multiple tasks)
• Efficiency opportunities missed (parallelization)
• Action: Log to TodoWrite, mention in end-of-session summary

INFO (Observation)

• Workflow variations that are acceptable
• Optimization suggestions
• Action: Track for pattern analysis only

Report Template

## 🚨 Routing Violation Detected

**Severity**: CRITICAL

**Workflow Type**: [status-change / feature-creation / etc.]

**Violation**: [Description]

**Impact**: [What this affects]

**Expected Approach**: Use [Skill Name] Skill

**Actual Approach**: Direct tool call / Subagent / etc.

**Recommendation**: [How to correct]

---

**Added to TodoWrite**:
- Review [Workflow]: [Issue description]

**Decision Required**: Should orchestrator retry using correct Skill?

Common Violations

Violation 1: Direct Status Change

User: "Mark task T1 complete"
Orchestrator: manage_container(operation="setStatus", status="completed")  // ❌

Expected: Use Status Progression Skill
Reason: Summary validation, dependency checks required

Violation 2: Direct Feature Creation

User: "Create user authentication feature"
Orchestrator: manage_container(operation="create", containerType="feature")  // ❌

Expected: Use Feature Orchestration Skill
Reason: Complexity assessment, template discovery required

Violation 3: Specialist Bypass

Backend Engineer: manage_container(operation="setStatus", status="completed")  // ❌

Expected: Use Status Progression Skill in Step 8
Reason: Summary, Files Changed, test validation required

Integration with Post-Execution Review

// ALWAYS run routing validation in post-execution
Read "routing-validation.md"

violations = detectRoutingViolations(
  workflowType,
  entityType,
  entityOutput,
  context
)

if (violations.length > 0) {
  for violation in violations:
    if (violation.severity == "CRITICAL") {
      // Report immediately
      alertUser(violation)
      addToTodoWrite(violation)
    } else {
      // Log for summary
      logViolation(violation)
    }
}

Continuous Improvement

Pattern Tracking

If same violation occurs 2+ times in session:

• Update orchestrator instructions
• Add validation checkpoint in pre-execution
• Suggest systemic improvement

Definition Updates

Recurring violations indicate documentation gaps:

• Update Skill definitions with clearer trigger patterns
• Add examples of correct vs incorrect usage
• Update CLAUDE.md Decision Gates section

When to Report

• CRITICAL violations: Report immediately (don't wait for post-execution)
• WARN violations: Include in post-execution summary
• INFO observations: Track for pattern analysis only