# Clarify

> Refine an existing feature specification through targeted clarification dialogue. Use when a spec.md contains ambiguities — vague roles, non-testable requirements, unclear entities — that should be resolved before generating the doc chain.

- Skill: `app-builders-club/clarify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add app-builders-club/clarify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/app-builders-club/clarify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: app-builders-club (https://skillmd.com/u/app-builders-club)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/app-builders-club/clarify

---


# Instructions

Interactive skill that refines existing feature specifications through targeted clarification dialogue.

**Input:** `$ARGUMENTS` — feature path (e.g. `ai-docs/features/cv-upload`). If empty, ask the user which feature to clarify.

**Tools Usage:**
- `Read`: For loading current spec state
- `Write`: For incremental spec updates after clarifications
- `Bash`: For file operations

**Skills:**
- Document Templates: For canonical spec.md structure
  - Read the template from the doc-templates skill before processing
- Sequential Thinking Methodology: For analyzing section coherence and validating clarification consistency
  - Tool: the sequential-thinking MCP tool

**Template (doc-templates skill — read before processing):** `references/spec-template.md`

# Task

Refine the existing spec.md by:
1. Reading and analyzing current spec.md content
2. Processing each template section sequentially
3. Identifying and resolving ambiguities within sections
4. Updating ONLY existing content with clarifications
5. Preserving structure and formatting

# Rules

## Critical Rule
**NEVER make assumptions.** When encountering ambiguity:
- DO NOT guess or use defaults
- MUST ask user for clarification
- WAIT for actual response before proceeding
- ONLY update existing template sections
- PRESERVE all existing content and structure

## Processing Constraints
- Work within existing template sections only
- Maximum 5 clarification questions per section
- Make minimal changes for maximum clarity
- Never add new sections or categories
- Never remove content without replacement

# Execution Flow

## 1. Initialize
- Resolve feature path from `$ARGUMENTS`; SPEC_FILE = `[feature-path]/spec.md`
- If SPEC_FILE missing → "spec.md not found at [feature-path]. Run /feature first."
- Read current spec.md content
- Parse template sections
- Identify sections with content

## 2. Process Each Section

### 2.1 Scan for Ambiguities
Check section content against these patterns:

**Primary User Story:**
- Vague roles: "users", "people", "someone"
- Unclear goals: "manage stuff", "handle things"  
- Missing context: when/why feature is used

**Acceptance Scenarios:**
- Non-specific states: "system is ready"
- Ambiguous actions: "user does something"
- Vague outcomes: "it works correctly"

**Edge Cases:**
- Generic descriptions: "error handling"
- Unspecified behaviors: "handle appropriately"
- Missing recovery actions

**Functional Requirements:**
- Non-testable metrics: "should be fast"
- Missing bounds: "handle many"
- Unclear priorities: MUST vs SHOULD

**UX Requirements:**
- Generic interactions: "user-friendly"
- Unspecified feedback: "show message"
- Missing error states

**Key Entities:**
- Undefined relationships: "related to"
- Missing cardinalities
- Vague attributes: "some data"

**Technical Context:**
- Unclear constraints: "performance limits", "scalability requirements"
- Vague tech stack: "modern framework", "standard tools"

### 2.2 Collect Clarifications
If ambiguities found:
- Generate numbered list of questions (max 5)
- Each question must be answerable with:
  * Multiple-choice selection, OR
  * Short phrase/value
- Present all questions for section at once

Example format:
```
Analyzing [Section Name]...
Found ambiguities:

1. In "Users can manage content", what type of users?
   a) Admins 
   b) Editors 
   c) Viewers

2. In "System MUST be fast", specify response time:
   Format: number+unit (e.g., "500ms")

Please answer all: (e.g., "1:b, 2:500ms")
```

### 2.3 Analyze Section Coherence
After receiving ALL answers for section:

**Apply Sequential Thinking Methodology** for coherence analysis:
- Verify clarifications are mutually consistent
- Check section completeness
- Validate testability improvement

### 2.4 Update Section
- Show before/after comparison
- Wait for user confirmation ("ok")
- Read current SPEC_FILE
- Apply all clarifications to section atomically
- Preserve formatting and structure
- Write back to SPEC_FILE
- Log: "✅ Clarified [section name]"

## 3. Complete Processing
After all sections processed:
- Validate cross-section consistency
- Ensure no contradictions introduced
- Verify all requirements testable

## 4. Final Report
```
Clarification Complete

- Sections clarified: [list]
- Total ambiguities resolved: [count]
- Status: SUCCESS (spec refined and ready)

Next: feature-docs agent <feature-path>
```

# Examples

## Simple Clarification
**Before:** "FR-001: System MUST be fast"  
**Question:** "What specific response time - under 2s, 500ms, 100ms?"  
**Answer:** "500ms"  
**After:** "FR-001: System MUST respond within 500ms"

## Entity Clarification  
**Before:** "User: represents someone in system"  
**Question:** "What defines a unique user - email, username, or ID?"  
**Answer:** "email"  
**After:** "User: represents account holder, unique by email"

## Role Clarification
**Before:** "Users can manage their content"  
**Question:** "What type of users - admins, editors, or viewers?"  
**Answer:** "editors"  
**After:** "Content editors can manage their published articles"

# Error Conditions

- ERROR: Attempting to add new sections
- ERROR: More than 5 clarifications needed per section  
- ERROR: Breaking template structure
- WARN: Removing content without replacement