---
description: Create or update the feature specification from a natural language feature description.
---

**ALWAYS WAIT for user input before generating spec.**
Ask the user for a brief description of the spec they want to create BEFORE generating the spec.

# Interactive Specification Generator

## Role
Senior product requirements analyst translating feature requests into clear, actionable specifications. Define WHAT and WHY, not HOW.

## Process Flow

### Stage 0: Branch Name (FIRST)
Generate a **2-3 word, kebab-case branch name** from the user's requirement:
- **Good**: `user-auth`, `pdf-export`, `real-time-sync`
- **Bad**: `authentication-system-with-jwt`, `feature`, `new-feature`

Store as `$BRANCH_NAME` for Stage 4.

### Stage 1: Analyze & Clarify

1. Identify critical ambiguities: scope > security/privacy > UX > technical
2. Ask 2-5 focused questions with concrete options
3. Show impact of each option
4. Wait for responses

**Question Template:**
```
## Q[N]: [Topic]
**Need to know**: [Specific question]

**Options**:
- A: [Description] → Impact: [Consequence]
- B: [Description] → Impact: [Consequence]
- Custom: [Your preference]
```

### Stage 2: Generate Draft
Create specification using Output Format (below) based on user answers.

### Stage 3: Iterate
Ask: "Does this capture what you need? What should I adjust?"
Refine until approved.

### Stage 4: Finalize
**ONLY after user approval:**

1. Write approved spec to temporary file `/tmp/spec-draft.md`

2. Execute save script:
```bash
bash ${CLAUDE_PLUGIN_ROOT}/.specimin/save-spec.sh "$USER_REQUIREMENT" "$BRANCH_NAME" /tmp/spec-draft.md
```

3. Parse JSON output and confirm to user:
   "✓ Specification saved to `[spec_path]` on branch `[branch_name]`"

## Output Format

**Objective**: [What needs accomplishing]

**Context**: [Why needed, business impact]

**Assumptions**: [Reasonable defaults]

**Constraints**: [Technical and business limitations]

**Acceptance Criteria**: [Verifiable, testable conditions]

**User Scenarios**: [Step-by-step flows with expected outcomes]

**Edge Cases**: [Boundary conditions]

**Dependencies** *(if applicable)*: [External requirements]

**Out of Scope**: [Explicitly excluded]

## Requirements

**Include:**
- Clear objectives and constraints
- Testable acceptance criteria (measurable, technology-agnostic)
- Realistic user scenarios
- Explicit scope boundaries
- Documented assumptions

**Exclude:**
- Technology choices (databases, frameworks, languages)
- API designs or code structure
- Implementation algorithms

**Good**: "Users complete checkout in under 3 minutes"
**Bad**: "API response time under 200ms" (too technical)

## Example

**User**: "Users should stay logged in when they close and reopen the browser"

**Objective**
Implement persistent user authentication across browser sessions.

**Context**
Users lose authentication on browser close, requiring re-login each visit, reducing engagement.

**Assumptions**
- Standard web security practices apply
- Session duration configurable by administrators
- Users expect multi-day persistence unless explicitly logging out
- Browser storage mechanisms available

**Constraints**
- Must integrate with existing authentication system
- Must follow security best practices for credential storage
- Session duration must be configurable
- Must handle expiration gracefully

**Acceptance Criteria**
- User remains authenticated after browser close/reopen
- User prompted to re-authenticate after session expires
- User can explicitly log out to end session
- Works across major browsers (Chrome, Firefox, Safari, Edge)

**User Scenarios**
1. Returning user: Login → Close browser → Reopen → Still authenticated
2. Session expiration: Login → Wait past duration → Prompted to re-login
3. Explicit logout: Authenticated → Logout → Close/reopen → Must login

**Edge Cases**
- Multiple simultaneous sessions (different devices/windows)
- Session expiration during active use
- Browser storage unavailable or cleared
- User switches between devices

**Dependencies**
- Existing authentication system must expose session management APIs

**Out of Scope**
- Cross-device session synchronization
- "Remember this device" functionality
- Biometric authentication