Spec Iterator

# Stop Building Features Based on Assumptions

**Spec Iterator** conducts structured AI-powered clarification sessions that systematically uncover gaps in your requirements *before* you write code.

---

## The Problem Everyone Ignores

```
Stakeholder: "Build a dashboard for our sales team"
↓
You build it
↓
Stakeholder: "Where's the pipeline view?"
↓
You: "You didn't mention that"
↓
Stakeholder: "I assumed it was obvious"
↓
💸 2 weeks of rework
```

**Requirements arrive incomplete.** Stakeholders don't know what they don't know. The "obvious" features only become obvious after you ship the wrong thing.

---

## How Spec Iterator Works

```
┌─────────────────────────────────────────────────────────────┐
│ "We need order tracking for customers" │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 🔍 ANALYZE │
│ ───────────────────────────────────────────────────────── │
│ • Entities detected: orders, customers, tracking │
│ • Gaps found: users undefined, stages unclear, no UX │
│ • Completeness: 12% │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ ❓ CLARIFY (Round 1) │
│ ───────────────────────────────────────────────────────── │
│ 1. Who are the primary users of this tracking system? │
│ 2. What order stages should be visible to customers? │
│ 3. Should users receive notifications? Which events? │
│ 4. What systems contain order data today? │
└─────────────────────────────────────────────────────────────┘
↓
[You provide answers]
↓
┌─────────────────────────────────────────────────────────────┐
│ ❓ CLARIFY (Round 2) — Completeness: 48% │
│ ───────────────────────────────────────────────────────── │
│ 1. Email or SMS for notifications? Or both? │
│ 2. Real-time tracking needed or periodic updates? │
│ 3. What about returns and exchanges? │
│ 4. Mobile app or web only? │
└─────────────────────────────────────────────────────────────┘
↓
[You provide answers]
↓
┌─────────────────────────────────────────────────────────────┐
│ ✅ READY — Completeness: 84% │
│ ───────────────────────────────────────────────────────── │
│ All critical gaps resolved. Ready to generate spec. │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 📄 GENERATE │
│ ───────────────────────────────────────────────────────── │
│ • Problem statement with user personas │
│ • Step-by-step user flow │
│ • Features with acceptance criteria │
│ • Edge cases with handling strategies │
│ • Documented assumptions │
│ • Open questions for stakeholders │
└─────────────────────────────────────────────────────────────┘
```

---

## Completeness Scoring

Track exactly what's missing across **5 categories**:

| Category | Weight | What It Covers |
|----------|--------|----------------|
| **Functional** | 30% | Features, users, business rules |
| **Technical** | 25% | Integrations, data, APIs |
| **UX** | 20% | Flows, errors, accessibility |
| **Edge Cases** | 15% | Errors, boundaries, recovery |
| **Constraints** | 10% | Budget, compliance, scale |

**Example output:**
```
Completeness: 73%
├── Functional: ████████░░ 85%
├── Technical: ██████░░░░ 60%
├── UX: ███████░░░ 75%
├── Edge Cases: █████░░░░░ 55%
└── Constraints: ████████░░ 80%

⚠️ Technical gaps: Data refresh frequency, API rate limits
⚠️ Edge cases: Offline handling, partial order updates
```

---

## Tools Included

| Tool | Description |
|------|-------------|
| `spec_start_session` | Start clarification from a rough requirement |
| `spec_answer_questions` | Provide answers, receive follow-up questions |
| `spec_get_gaps` | See exactly what's missing and the impact |
| `spec_generate` | Generate complete specification |
| `spec_get_status` | Check session progress |
| `spec_list_sessions` | List all active sessions |

---

## Sample Output

```markdown
# Order Tracking System

## Problem Statement
**Pain:** Customers have no visibility into order status after purchase
**Who:** E-commerce customers, support team
**Workarounds:** Calling support, checking email for shipping updates

## Features

### 1. Order Status Page (MVP)
Customers can view real-time order status on a dedicated page.

**Acceptance Criteria:**
- [ ] Display order stages: Confirmed → Processing → Shipped → Delivered
- [ ] Show estimated delivery date
- [ ] Update within 5 minutes of status change
- [ ] Accessible without login via order ID + email

### 2. Email Notifications (MVP)
Automated emails at key order milestones.

**Acceptance Criteria:**
- [ ] Send on: order confirmed, shipped, out for delivery, delivered
- [ ] Include tracking link when available
- [ ] Unsubscribe option per notification type

## Edge Cases
| Scenario | Handling |
|----------|----------|
| Order stuck in "Processing" > 48h | Trigger support alert |
| Tracking number not yet available | Show "Tracking available soon" |
| Multiple shipments per order | Show each shipment separately |
```

---

## Who It's For

**Product Managers** → Stop missing requirements that cause rework

**Tech Leads** → Don't estimate incomplete requirements

**Solo Developers** → Think through requirements systematically

**Startup Founders** → Document ideas with implementation detail

**Consultants** → Standardize discovery across clients

---

## Configuration

Requires your Anthropic API key:

| Parameter | Description |
|-----------|-------------|
| `ANTHROPIC_API_KEY` | Your Anthropic API key |

**You pay Claude directly** — typical spec costs $0.05-0.15 in API usage (3-5 rounds of clarification).

---

## Quick Start

1. **Connect** Spec Iterator in Claude Desktop
2. **Run:** `spec_start_session` with your rough requirement
3. **Answer** the clarifying questions
4. **Generate** when completeness hits 80%+

---

## Resources

- **GitHub:** [Repository](https://github.com/JesseHenson/claude_code_apex_marketplace/tree/master/plugins/spec-iterator-mcp)
- **Demo:** Coming soon
- **Support:** Open an issue on GitHub

---

## Version

**v0.1.0** — Initial release

- Multi-turn clarification flow
- Completeness scoring (5 categories)
- Markdown and JSON output
- Session persistence

Site: https://aibusinessautomation.solutions/