when-analyzing-user-intent-use-intent-analyzer

What this skill does

# Intent Analyzer - Advanced User Intent Interpretation

## Overview

Advanced intent interpretation system that analyzes user requests using cognitive science principles and extrapolates logical volition. Use when user requests are ambiguous, when deeper understanding would improve response quality, or when helping users clarify what they truly need.

## When to Use This Skill

- User request is vague or ambiguous
- Multiple interpretations are possible
- High-stakes decision requires clarity
- User may not know exactly what they need
- Complex requirements need decomposition
- Implicit assumptions need surfacing

## Theoretical Foundation

### Cognitive Science Principles

1. **Probabilistic Intent Mapping**: Assign likelihood scores to possible interpretations
2. **First Principles Decomposition**: Break complex requests into fundamental components
3. **Socratic Clarification**: Ask targeted questions to narrow possibilities
4. **Context Integration**: Leverage environment and history for disambiguation
5. **Volition Extrapolation**: Infer underlying goals beyond stated request

### Evidence-Based Patterns

- **Self-Consistency**: Generate multiple interpretations and find consensus
- **Chain-of-Thought**: Trace reasoning from input to understanding
- **Program-of-Thought**: Structure analysis as executable logic
- **Plan-and-Solve**: Decompose understanding into steps

## Phase 1: Capture User Input

### Objective
Gather complete user request with full context

### Agent Coordination
```bash
# Pre-task hook
npx claude-flow@alpha hooks pre-task \
  --description "Capture user input for intent analysis" \
  --complexity "low" \
  --expected-duration "2min"

# Session restore
npx claude-flow@alpha hooks session-restore \
  --session-id "intent-analyzer-${TIMESTAMP}"
```

### Implementation

**Step 1.1: Extract Raw Input**
```javascript
const userInput = {
  request: "[User's exact words]",
  context: {
    environment: process.env,
    workingDirectory: process.cwd(),
    recentHistory: [] // Last 5 interactions
  },
  timestamp: new Date().toISOString()
};

// Store in memory
await memory.store('intent/raw-input', userInput);
```

**Step 1.2: Identify Input Characteristics**
```javascript
const characteristics = {
  length: userInput.request.split(' ').length,
  hasMultipleParts: /and|then|also|additionally/i.test(userInput.request),
  containsQuestions: /\?/.test(userInput.request),
  specificityScore: calculateSpecificity(userInput.request),
  domainIndicators: extractDomains(userInput.request)
};

await memory.store('intent/characteristics', characteristics);
```

**Step 1.3: Gather Context Clues**
```javascript
const contextClues = {
  fileSystem: await analyzeFileSystem(),
  recentEdits: await getRecentEdits(),
  projectType: await inferProjectType(),
  userExpertise: await estimateExpertiseLevel()
};

await memory.store('intent/context-clues', contextClues);
```

### Validation Criteria
- [ ] Complete user request captured
- [ ] Context information gathered
- [ ] Characteristics identified
- [ ] Memory storage confirmed

### Memory Pattern
```bash
# Store phase completion
npx claude-flow@alpha hooks post-edit \
  --file "memory://intent/raw-input" \
  --memory-key "intent-analyzer/phase1/completion"
```

## Phase 2: Decompose Intent

### Objective
Break down request into fundamental components using first principles

### Agent: Researcher

**Step 2.1: Tokenize Request**
```javascript
const tokens = {
  actions: extractActionVerbs(userInput.request),
  subjects: extractSubjects(userInput.request),
  constraints: extractConstraints(userInput.request),
  outcomes: extractDesiredOutcomes(userInput.request)
};

// Example output:
// {
//   actions: ['create', 'optimize', 'test'],
//   subjects: ['API', 'database', 'authentication'],
//   constraints: ['must be secure', 'under 100ms'],
//   outcomes: ['production-ready', 'scalable']
// }
```

**Step 2.2: Build Component Tree**
```javascript
const componentTree = {
  primary: {
    intent: inferPrimaryIntent(tokens),
    confidence: 0.85
  },
  secondary: tokens.actions.slice(1).map(action => ({
    intent: action,
    confidence: 0.60
  })),
  implicit: inferImplicitRequirements(tokens, contextClues)
};

await memory.store('intent/component-tree', componentTree);
```

**Step 2.3: Identify Dependencies**
```javascript
const dependencies = {
  sequential: findSequentialDeps(componentTree),
  parallel: findParallelDeps(componentTree),
  conditional: findConditionalDeps(componentTree)
};

// Example:
// {
//   sequential: ['database schema' -> 'API endpoints' -> 'tests'],
//   parallel: ['frontend', 'backend'],
//   conditional: ['if authentication: setup OAuth']
// }
```

### Validation Criteria
- [ ] All action verbs identified
- [ ] Component tree constructed
- [ ] Dependencies mapped
- [ ] Implicit requirements surfaced

### Script Template
```bash
#!/bin/bash
# decompose-intent.sh

INPUT_FILE="$1"
OUTPUT_FILE="$2"

# Read user input
USER_REQUEST=$(cat "$INPUT_FILE")

# Decompose using researcher agent
npx claude-flow@alpha agent-spawn \
  --type researcher \
  --task "Decompose this request into components: $USER_REQUEST" \
  --output "$OUTPUT_FILE"

# Store results
npx claude-flow@alpha hooks post-edit \
  --file "$OUTPUT_FILE" \
  --memory-key "intent-analyzer/decomposition"
```

## Phase 3: Map Probabilities

### Objective
Assign likelihood scores to possible interpretations

### Agent: Analyst

**Step 3.1: Generate Interpretation Candidates**
```javascript
const interpretations = [
  {
    id: 'interp-1',
    description: 'User wants a complete REST API with authentication',
    probability: 0.75,
    evidence: ['mentions API', 'security constraint'],
    assumptions: ['Express.js framework', 'JWT auth']
  },
  {
    id: 'interp-2',
    description: 'User wants to add auth to existing API',
    probability: 0.20,
    evidence: ['existing project detected'],
    assumptions: ['API already exists']
  },
  {
    id: 'interp-3',
    description: 'User wants auth documentation/research',
    probability: 0.05,
    evidence: ['vague phrasing'],
    assumptions: ['exploratory phase']
  }
];

await memory.store('intent/interpretations', interpretations);
```

**Step 3.2: Apply Bayesian Reasoning**
```javascript
function updateProbabilities(interpretations, newEvidence) {
  return interpretations.map(interp => {
    const priorProb = interp.probability;
    const likelihoodGivenEvidence = calculateLikelihood(interp, newEvidence);
    const posteriorProb = (priorProb * likelihoodGivenEvidence) /
                          calculateNormalization(interpretations, newEvidence);

    return { ...interp, probability: posteriorProb };
  });
}

const updatedInterpretations = updateProbabilities(interpretations, contextClues);
```

**Step 3.3: Rank by Confidence**
```javascript
const rankedInterpretations = updatedInterpretations
  .sort((a, b) => b.probability - a.probability)
  .map((interp, index) => ({
    ...interp,
    rank: index + 1,
    confidenceLevel: interp.probability > 0.8 ? 'HIGH' :
                     interp.probability > 0.5 ? 'MEDIUM' : 'LOW'
  }));

await memory.store('intent/ranked-interpretations', rankedInterpretations);
```

### Validation Criteria
- [ ] At least 3 interpretations generated
- [ ] Probabilities sum to ~1.0
- [ ] Evidence listed for each interpretation
- [ ] Confidence levels assigned

### Memory Pattern
```bash
# Store probability analysis
npx claude-flow@alpha hooks post-task \
  --task-id "probability-mapping" \
  --metrics '{"interpretations": 3, "top_confidence": 0.75}'
```

## Phase 4: Clarify Ambiguities

### Objective
Ask targeted questions to resolve uncertainty

### Agent: Planner

**Step 4.1: Identify Decision Points**
```javascript
const ambiguities = rankedInterpretations.flatMap(interp => {
  if (interp.probability < 0.8 && interp.rank <= 2) {
    return interp.assumptions.map(assumption => ({
      interpretation: interp.id,
      assumption: assumption,