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/