clarification-protocol

# Clarification Protocol

Generates focused, challenging questions to extract missing context and clarify vague requirements before routing to specialist agents.

## When to Use

- After request-analyzer identifies vague terms or missing context
- When requirements are ambiguous and could lead to wrong solutions
- Before delegating to cto-architect or strategic-cto-mentor
- When buzzwords need to be translated into specific requirements

## Core Principles

### 1. Maximum 2-3 Questions Per Round

Users lose patience with long questionnaires. Prioritize ruthlessly:
- Ask only what's blocking progress
- Combine related questions
- Defer nice-to-have information

### 2. Challenge Mode, Not Interview Mode

Don't just ask—challenge assumptions:
- Bad: "What scale do you need?"
- Good: "You mentioned 'scalable'—are we designing for 10K users or 10M? That changes the architecture significantly."

### 3. Provide Example Answers

Help users understand what you're looking for:
- Bad: "What's your timeline?"
- Good: "What's your timeline? For context, a robust MVP typically takes 8-12 weeks with a team of 4."

## Question Generation Framework

### Step 1: Prioritize Missing Information

Rank by impact on routing and design:

| Priority | Category | Examples |
|----------|----------|----------|
| **P0** | Blocking | Can't proceed without this (e.g., "What problem does AI solve here?") |
| **P1** | High Impact | Significantly changes approach (e.g., "1K or 100K users?") |
| **P2** | Medium Impact | Affects details but not direction (e.g., "Budget range?") |
| **P3** | Nice to Have | Can be discovered later (e.g., "Preferred cloud provider?") |

**Ask P0 first, then P1. Defer P2/P3.**

### Step 2: Select Question Type

| Type | When to Use | Template |
|------|-------------|----------|
| **Scope** | Vague feature description | "When you say [X], do you mean [A] or [B]?" |
| **Scale** | Missing numbers | "What scale are we designing for? [X] users? [Y] requests/second?" |
| **Timeline** | Vague deadlines | "What's the actual deadline? Is there flexibility if scope changes?" |
| **Constraint** | Unknown limitations | "Are there constraints I should know about? Budget, team size, existing systems?" |
| **Success** | Unclear goals | "How will we know this succeeded? What metrics matter?" |

### Step 3: Frame as Challenge

Transform neutral questions into challenging ones:

| Neutral (Weak) | Challenge (Strong) |
|----------------|-------------------|
| "What do you mean by AI-powered?" | "'AI-powered' can mean many things—are you trying to classify data, generate content, or make predictions? What specific problem are you solving?" |
| "What's your budget?" | "Knowing budget helps me avoid over-engineering. Are we optimizing for < $5K/month or is $50K/month acceptable for the right solution?" |
| "How many users?" | "You mentioned 'scale'—I want to avoid designing for problems you don't have. How many users today, and what's realistic in 12 months?" |

## Output Format

```
## Clarification Needed

Before I route this to the appropriate specialist, I need to understand a few things:

### Challenge 1: [Vague Term/Concept]
[Direct challenge statement]

**Question**: [Specific question]

**Why this matters**: [Impact on design/routing]

**Example answers**:
- Option A: [example] → leads to [approach]
- Option B: [example] → leads to [different approach]

### Challenge 2: [Missing Context]
[...]

---

Once you clarify these points, I'll route to [suggested agent] with a clear brief.
```

## Question Templates by Category

See [question-templates.md](question-templates.md) for comprehensive templates.

See [challenge-patterns.md](challenge-patterns.md) for examples of turning neutral questions into challenges.

## Examples

### Example 1: AI Feature Request

**User Request**: "We want to add AI capabilities to improve customer experience"

**Clarification Output**:

```
## Clarification Needed

Before I route this to cto-architect, I need to understand what "AI capabilities" means for your use case:

### Challenge 1: Vague AI Requirement
"AI capabilities" could mean anything from a chatbot to predictive analytics. I don't want to design the wrong solution.

**Question**: What specific customer problem are you trying to solve with AI?

**Why this matters**: A recommendation engine has completely different architecture than a support chatbot.

**Example answers**:
- "Customers can't find products" → Recommendation engine / search improvement
- "Support tickets are overwhelming" → AI-assisted ticket routing or chatbot
- "Churn is high" → Predictive analytics for at-risk customers

### Challenge 2: Missing Scale
**Question**: How many customers are we talking about? And how many interactions per day would this AI feature handle?

**Why this matters**: 1,000 daily interactions vs 1,000,000 changes whether we use a simple API call or need dedicated ML infrastructure.

---

Once you clarify these points, I'll route to cto-architect with a clear brief for the appropriate AI architecture.
```

### Example 2: Scaling Concerns

**User Request**: "Our app needs to scale better"

**Clarification Output**:

```
## Clarification Needed

"Scale better" is a symptom—I need to understand the disease before prescribing treatment.

### Challenge 1: What's Actually Broken?
**Question**: What specific scaling issue are you experiencing? Slow page loads? Database timeouts? High infrastructure costs? All of the above?

**Why this matters**: Scaling a slow database is different from scaling a CPU-bound API.

**Example answers**:
- "Page loads take 5+ seconds at peak" → Likely caching/CDN solution
- "Database queries timing out" → Database scaling or query optimization
- "AWS bill doubled last month" → Cost optimization vs actual scaling

### Challenge 2: Current vs Target Scale
**Question**: What's your current traffic, and what do you need to support? Be specific: requests per second, concurrent users, data volume.

**Why this matte