Initial commit

skills/orchestration-qa/token-optimization.md

@@ -0,0 +1,230 @@
+# Token Optimization Analysis
+
+**Purpose**: Identify token waste patterns and optimization opportunities.
+
+**When**: Optional post-execution (controlled by enableEfficiencyAnalysis parameter)
+
+**Applies To**: All Skills and Subagents
+
+**Token Cost**: ~400-600 tokens
+
+## Common Token Waste Patterns
+
+### Pattern 1: Verbose Specialist Output
+
+**Issue**: Specialist returns full code/documentation in response instead of brief summary
+
+**Expected**: Specialists return 50-100 token summary, detailed work goes in sections/files
+
+**Detection**:
+```javascript
+if (isImplementationSpecialist(entityType) && estimateTokens(output) > 200) {
+  return {
+    severity: "WARN",
+    pattern: "Verbose specialist output",
+    actual: estimateTokens(output),
+    expected: "50-100 tokens",
+    savings: estimateTokens(output) - 100,
+    recommendation: "Return brief summary, put details in task sections"
+  }
+}
+```
+
+### Pattern 2: Reading with includeSections When Not Needed
+
+**Issue**: Loading all sections when only metadata needed
+
+**Expected**: Use scoped `overview` for hierarchical views without sections
+
+**Detection**:
+```javascript
+if (mentions(output, "includeSections=true") && !needsSections(workflowType)) {
+  return {
+    severity: "INFO",
+    pattern: "Unnecessary section loading",
+    recommendation: "Use operation='overview' for metadata + task list",
+    savings: "85-93% tokens (e.g., 18.5k → 1.2k for typical feature)"
+  }
+}
+```
+
+### Pattern 3: Multiple Get Operations Instead of Overview
+
+**Issue**: Calling `query_container(operation="get")` multiple times instead of one overview
+
+**Expected**: Single scoped overview provides hierarchical view efficiently
+
+**Detection**:
+```javascript
+getCallCount = countToolCalls(output, "query_container", "get")
+if (getCallCount > 1 && !usedOverview) {
+  return {
+    severity: "INFO",
+    pattern: "Multiple get calls instead of overview",
+    actual: `${getCallCount} get calls`,
+    expected: "1 scoped overview call",
+    savings: estimateSavings(getCallCount)
+  }
+}
+```
+
+### Pattern 4: Listing All Entities When Filtering Would Work
+
+**Issue**: Querying all tasks then filtering in code
+
+**Expected**: Use query parameters (status, tags, priority) for filtering
+
+**Detection**:
+```javascript
+if (mentions(output, "filter") && !usedQueryFilters) {
+  return {
+    severity: "INFO",
+    pattern: "Client-side filtering instead of query filters",
+    recommendation: "Use status/tags/priority parameters in query_container",
+    savings: "~50-70% tokens"
+  }
+}
+```
+
+### Pattern 5: PRD Content in Description Instead of Sections
+
+**Issue**: Feature Architect puts all PRD content in description field
+
+**Expected**: Description is forward-looking summary; PRD sections go in feature sections
+
+**Detection**:
+```javascript
+if (entityType == "feature-architect" && feature.description.length > 800) {
+  return {
+    severity: "WARN",
+    pattern: "PRD content in description field",
+    actual: `${feature.description.length} chars`,
+    expected: "200-500 chars description + sections for detailed content",
+    recommendation: "Move detailed content to feature sections"
+  }
+}
+```
+
+### Pattern 6: Verbose Feature Architect Handoff
+
+**Issue**: Feature Architect returns detailed feature explanation
+
+**Expected**: Minimal handoff (50-100 tokens): "Feature created, ID: X, Y tasks ready"
+
+**Detection**:
+```javascript
+if (entityType == "feature-architect" && estimateTokens(output) > 200) {
+  return {
+    severity: "WARN",
+    pattern: "Verbose Feature Architect handoff",
+    actual: estimateTokens(output),
+    expected: "50-100 tokens",
+    savings: estimateTokens(output) - 100,
+    recommendation: "Brief handoff: Feature ID, next action. Details in feature sections."
+  }
+}
+```
+
+## Analysis Workflow
+
+### Step 1: Estimate Token Usage
+
+```javascript
+tokenUsage = {
+  input: estimateTokens(context.userInput.fullText),
+  output: estimateTokens(entityOutput),
+  total: estimateTokens(context.userInput.fullText) + estimateTokens(entityOutput)
+}
+```
+
+### Step 2: Compare Against Expected Range
+
+```javascript
+expectedRange = definition.tokenRange  // e.g., [1800, 2200] for Feature Architect
+deviation = tokenUsage.output - expectedRange[1]
+
+if (deviation > expectedRange[1] * 0.5) {  // More than 50% over
+  severity = "WARN"
+} else {
+  severity = "INFO"
+}
+```
+
+### Step 3: Detect Waste Patterns
+
+```javascript
+wastePatterns = []
+
+// Check each pattern
+if (verboseSpecialistOutput()) wastePatterns.push(pattern1)
+if (unnecessarySectionLoading()) wastePatterns.push(pattern2)
+if (multipleGetsInsteadOfOverview()) wastePatterns.push(pattern3)
+if (clientSideFiltering()) wastePatterns.push(pattern4)
+if (prdContentInDescription()) wastePatterns.push(pattern5)
+if (verboseHandoff()) wastePatterns.push(pattern6)
+```
+
+### Step 4: Calculate Potential Savings
+
+```javascript
+totalSavings = wastePatterns.reduce((sum, pattern) => sum + pattern.savings, 0)
+optimizedTokens = tokenUsage.total - totalSavings
+efficiencyGain = (totalSavings / tokenUsage.total) * 100
+```
+
+### Step 5: Generate Report
+
+```markdown
+## 💡 Token Optimization Opportunities
+
+**Current Usage**: [X] tokens
+**Potential Savings**: [Y] tokens ([Z]% reduction)
+**Optimized Usage**: [X - Y] tokens
+
+### Patterns Detected ([count])
+
+**⚠️ WARN** ([count]): Significant waste
+- Verbose specialist output: [X] tokens (expected 50-100)
+- PRD content in description: [Y] chars (expected 200-500)
+
+**ℹ️ INFO** ([count]): Optimization opportunities
+- Use overview instead of get: [savings] tokens
+- Use query filters: [savings] tokens
+
+### Recommendations
+1. [Most impactful optimization]
+2. [Secondary optimization]
+```
+
+## Recommended Baselines
+
+- **Skills**: 200-900 tokens (lightweight coordination)
+- **Feature Architect**: 1800-2200 tokens (complexity assessment + creation)
+- **Planning Specialist**: 1800-2200 tokens (analysis + task creation)
+- **Implementation Specialists**: 1800-2200 tokens (work done, not described)
+  - **Output**: 50-100 tokens (brief summary)
+  - **Sections**: Detailed work (not counted against specialist)
+
+## When to Report
+
+- **Only if** enableEfficiencyAnalysis=true
+- **WARN**: Include in post-execution report
+- **INFO**: Log for pattern tracking only
+
+## Integration Example
+
+```javascript
+if (params.enableEfficiencyAnalysis) {
+  Read "token-optimization.md"
+  opportunities = analyzeTokenOptimization(entityType, entityOutput, context)
+
+  if (opportunities.length > 0) {
+    report.efficiencyAnalysis = {
+      currentUsage: tokenUsage.total,
+      savings: totalSavings,
+      gain: efficiencyGain,
+      opportunities: opportunities
+    }
+  }
+}
+```