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 - 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/