clarify

# /clarify — Specification Clarifier (Thin Wrapper)

> **v11.0 Architecture**: This command spawns the isolated `clarify-phase-agent` via Task(). All clarification logic runs in isolated context with question batching.

<context>
**User Input**: $ARGUMENTS

**Active Feature**: !`ls -td specs/[0-9]*-* 2>/dev/null | head -1 || echo "none"`

**Interaction State**: !`cat specs/*/interaction-state.yaml 2>/dev/null | head -10 || echo "none"`
</context>

<objective>
Spawn isolated clarify-phase-agent to reduce specification ambiguity through targeted questions.

**Architecture (v11.0 - Phase Isolation):**
```
/clarify → Task(clarify-phase-agent) → Q&A loop if needed → updated spec.md
```

**Agent responsibilities:**
- Scan spec.md for `[NEEDS CLARIFICATION]` markers
- Map ambiguities to question bank templates
- Return batched questions (max 3 at a time)
- Apply answers atomically to spec.md
- Cite repo precedents for recommendations

**Key principle**: Planning is 80% of success — thorough clarification prevents costly rework.

**Workflow position**: `spec → clarify → plan → tasks → implement → optimize → ship`
</objective>

## Anti-Hallucination Rules

**CRITICAL**: Follow these rules to prevent fabricating ambiguities or solutions.

1. **Never invent ambiguities** not present in `spec.md`.

   - ❌ BAD: "The spec doesn't mention how to handle edge cases" (without reading it)
   - ✅ GOOD: Read spec.md, quote ambiguous sections: "spec.md:45 says 'users can edit' but doesn't specify edit permissions"
   - **Quote verbatim with line numbers:** `spec.md:120-125: '[exact quote]'`

2. **Always quote the unclear text** and cite **line numbers** for every question.

   - When flagging ambiguity: `spec.md:120-125: '[exact quote]' - unclear whether this means X or Y`
   - Don't paraphrase unclear text - show it verbatim
   - Cite line numbers for all ambiguities

3. **Never invent "best practice"** without evidence.

   - Don't say "Best practice is..." without evidence
   - Source recommendations: "Similar feature in specs/002-auth used JWT per plan.md:45"
   - If no precedent exists, say: "No existing pattern found, recommend researching..."

4. **Verify question relevance before asking user**.

   - Before asking technical question, check if answer exists in codebase
   - Use Grep/Glob to search for existing implementations
   - Don't ask "Should we use PostgreSQL?" if package.json already has pg installed

5. **Never assume user's answer without asking**.
   - Don't fill in clarifications with guesses
   - Present question, wait for response, use exact answer given
   - If user says "skip", mark as skipped - don't invent answer

**Why this matters**: Fabricated ambiguities create unnecessary work. Invented best practices may conflict with project standards. Accurate clarification based on real spec ambiguities ensures plan addresses actual uncertainties.

## Reasoning Approach

For complex clarification decisions, show your step-by-step reasoning:

<thinking>
Let me analyze this ambiguity:
1. What is ambiguous in spec.md? [Quote exact ambiguous text with line numbers]
2. Why is it ambiguous? [Explain multiple valid interpretations]
3. What are the possible interpretations? [List 2-3 options]
4. What's the impact of each interpretation? [Assess implementation differences]
5. Can I find hints in existing code or roadmap? [Search for precedents]
6. Conclusion: [Whether to ask user or infer from context]
</thinking>

<answer>
[Clarification approach based on reasoning]
</answer>

**When to use structured thinking:**

- Deciding whether ambiguity is worth asking about (impacts implementation vs cosmetic)
- Prioritizing multiple clarification questions (most impactful first)
- Determining if context provides sufficient hints to skip question
- Assessing whether to offer 2, 3, or 4 options
- Evaluating if recommended answer is justified by precedent

**Benefits**: Explicit reasoning reduces unnecessary questions by 30-40% and improves question quality.

---

<process>

### Step 0: WORKFLOW DETECTION

**Detect workflow using centralized skill** (see `.claude/skills/workflow-detection/SKILL.md`):

1. Run detection: `bash .spec-flow/scripts/utils/detect-workflow-paths.sh`
2. Parse JSON: Extract `type`, `base_dir`, `slug` from output
3. If detection fails (exit code != 0): Use AskUserQuestion fallback
4. Set paths:
   - Feature: `SPEC_FILE="${BASE_DIR}/${SLUG}/spec.md"`
   - Epic: `SPEC_FILE="${BASE_DIR}/${SLUG}/epic-spec.md"`

**Fallback prompt** (if detection fails):
- Question: "Which workflow are you working on?"
- Options: "Feature" (specs/), "Epic" (epics/)

**After detection**, count remaining ambiguities:
```bash
AMBIGUITY_COUNT=$(grep -c "\[NEEDS CLARIFICATION\]" "$SPEC_FILE" 2>/dev/null || echo "0")
```

---

### Step 1: AUTO-INVOCATION DETECTION (New in v5.0)

**When called from /epic workflow:**

The /epic command may auto-invoke /clarify based on ambiguity detection. This section determines if clarification is needed.

### Ambiguity Score Calculation

**Analyze epic-spec.md or spec.md:**

```javascript
const ambiguityScore = calculateAmbiguityScore({
  missing_subsystems: epic_spec.subsystems.filter(
    (s) => s.involved === "unknown"
  ).length,
  vague_objectives: epic_spec.objective.business_value.includes(
    "[NEEDS CLARIFICATION]"
  )
    ? 10
    : 0,
  missing_success_metrics: epic_spec.objective.success_metrics === "" ? 15 : 0,
  unclear_technical_approach:
    epic_spec.clarifications.length === 0 && epic_spec.constraints === ""
      ? 10
      : 0,
  placeholder_count: countPlaceholders(epic_spec) * 5,
});

// Score interpretation:
// 0-30: Clear (2-3 questions)
// 31-60: Moderate ambiguity (4-5 questions)
// 61+: High ambiguity (6-10 questions)
```

### Auto-Invoke Decision

```javascript
if (ambiguityScore > 30) {
  log(
    "🔍 Ambiguity detected (score: " +
      ambiguityScore +
      ") - Auto-invoking /clarify"
  );
  // Proceed with clarification workflow
} else if (ambiguit