@hustle-together/api-dev-tools 2.0.7 → 3.1.0

package/commands/api-interview.md

@@ -1,335 +1,331 @@
-# API Interview - Research-Based Structured Discovery
+# API Interview - Research-Driven Dynamic Discovery v3.0
 
 **Usage:** `/api-interview [endpoint-name]`
 
-**Purpose:** Conduct structured interview with MULTIPLE-CHOICE questions derived from research findings to understand API endpoint purpose, usage, and requirements before any implementation.
+**Purpose:** Conduct structured interview where questions are GENERATED FROM research findings, not generic templates. Every question is specific to the discovered API capabilities.
 
-## v1.8.0 REQUIREMENT: Structured Questions with Options
+## Key Principle: Questions FROM Research
 
-**CRITICAL:** All interview questions MUST:
-1. Be based on COMPLETED research (Context7 + WebSearch)
-2. Use AskUserQuestion tool with the `options` parameter
-3. Provide multiple-choice selections derived from research findings
-4. Include a "Type something else..." option for custom input
-
-**Example of CORRECT structured question:**
+**OLD WAY (Generic Templates):**
 ```
-AskUserQuestion(
-  question="Which AI provider should this endpoint support?",
-  options=[
-    {"value": "openai", "label": "OpenAI (GPT-4o, GPT-4-turbo)"},
-    {"value": "anthropic", "label": "Anthropic (Claude Sonnet, Opus)"},
-    {"value": "google", "label": "Google (Gemini Pro, Flash)"},
-    {"value": "all", "label": "All providers (multi-provider support)"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+"Which AI provider should this endpoint support?"
+- OpenAI
+- Anthropic
+- Google
 ```
 
-This gives users clear choices from RESEARCHED capabilities, not guesses.
-
-## Interview Methodology
-
-Based on Anthropic Interviewer approach with three phases:
-
-### Phase 0: PREREQUISITE - Research (MANDATORY)
-**You CANNOT start the interview until research is complete.**
-
-Before asking ANY questions:
-1. Use Context7 to get SDK/API documentation
-2. Use WebSearch (2-3 searches) for official docs
-3. Gather all available options, parameters, models, providers
-4. Build your question options FROM this research
-
-Example research flow:
-```
-1. mcp__context7__resolve-library-id("vercel ai sdk")
-2. mcp__context7__get-library-docs(libraryId)
-3. WebSearch("Vercel AI SDK providers models 2025")
-4. WebSearch("Vercel AI SDK streaming options parameters")
+**NEW WAY (From Research):**
 ```
+Based on research, Brandfetch API has 7 parameters:
 
-**Research informs options. No research = no good options = interview blocked.**
+1. DOMAIN (required) - string
+   → No question needed (always required)
 
-### Phase 1: Planning (Internal)
-- Review endpoint name and context
-- Review research findings (what providers, models, parameters exist?)
-- Build structured question options from research
-- Prepare follow-up questions
+2. FORMAT: ["json", "svg", "png", "raw"]
+   Q: Which formats do you need?
+   [x] json  [x] svg  [x] png  [ ] raw
 
-### Phase 2: Interviewing (User Interaction with Structured Options)
+3. QUALITY: 1-100 (continuous range)
+   Q: How should we TEST this continuous parameter?
+   [ ] All values (100 tests)
+   [x] Boundary (1, 50, 100)
+   [ ] Sample (1, 25, 50, 75, 100)
+   [ ] Custom: ____
+```
 
-**EVERY question uses AskUserQuestion with options parameter.**
+## Interview Flow
 
-#### A. Purpose & Context
+### Phase 0: PREREQUISITE - Research Must Be Complete
 
-**Question 1: Primary Purpose**
-```
-AskUserQuestion(
-  question="What is the primary purpose of this endpoint?",
-  options=[
-    {"value": "data_retrieval", "label": "Retrieve/query data"},
-    {"value": "data_transform", "label": "Transform/process data"},
-    {"value": "ai_generation", "label": "AI content generation"},
-    {"value": "ai_analysis", "label": "AI analysis/classification"},
-    {"value": "integration", "label": "Third-party integration"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
-```
+**Interview is BLOCKED until research is done.**
 
-**Question 2: Primary Users**
+The interview READS from the research findings:
 ```
-AskUserQuestion(
-  question="Who are the primary users of this endpoint?",
-  options=[
-    {"value": "frontend", "label": "Frontend developers (React, Vue, etc.)"},
-    {"value": "backend", "label": "Backend services (server-to-server)"},
-    {"value": "mobile", "label": "Mobile app developers"},
-    {"value": "enduser", "label": "End users directly (browser)"},
-    {"value": "automation", "label": "Automated systems/bots"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+State file shows:
+  research_initial.status = "complete"
+  research_initial.sources = [...]
+
+Discovered parameters:
+  - 5 required parameters
+  - 12 optional parameters
+  - 3 enum types
+  - 2 continuous ranges
 ```
 
-**Question 3: Usage Trigger**
-```
-AskUserQuestion(
-  question="What triggers a call to this endpoint?",
-  options=[
-    {"value": "user_action", "label": "User action (button click, form submit)"},
-    {"value": "page_load", "label": "Page/component load"},
-    {"value": "scheduled", "label": "Scheduled/cron job"},
-    {"value": "webhook", "label": "External webhook/event"},
-    {"value": "realtime", "label": "Real-time/streaming updates"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
-```
+### Phase 1: Parameter-Based Questions
 
-#### B. Technical Requirements (Research-Based Options)
+For each discovered parameter, generate an appropriate question:
 
-**Question 4: AI Provider** (options from research)
+#### Required Parameters (Confirmation Only)
 ```
-AskUserQuestion(
-  question="Which AI provider(s) should this endpoint support?",
-  options=[
-    // These options come from your Context7/WebSearch research!
-    {"value": "openai", "label": "OpenAI (gpt-4o, gpt-4-turbo)"},
-    {"value": "anthropic", "label": "Anthropic (claude-sonnet-4-20250514, claude-opus-4-20250514)"},
-    {"value": "google", "label": "Google (gemini-pro, gemini-flash)"},
-    {"value": "groq", "label": "Groq (llama-3.1-70b, mixtral)"},
-    {"value": "multiple", "label": "Multiple providers (configurable)"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ REQUIRED PARAMETERS                                        │
+│                                                            │
+│ These parameters are required by the API:                  │
+│                                                            │
+│ 1. domain (string) - The domain to fetch brand data for   │
+│ 2. apiKey (string) - Your Brandfetch API key              │
+│                                                            │
+│ Confirm these are understood? [Y/n]                        │
+└────────────────────────────────────────────────────────────┘
 ```
 
-**Question 5: Response Format** (options from research)
+#### Enum Parameters (Multi-Select)
 ```
-AskUserQuestion(
-  question="What response format is needed?",
-  options=[
-    // Options based on what the SDK supports (from research)
-    {"value": "streaming", "label": "Streaming (real-time chunks)"},
-    {"value": "complete", "label": "Complete response (wait for full)"},
-    {"value": "structured", "label": "Structured/JSON mode"},
-    {"value": "tool_calls", "label": "Tool calling/function calls"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ FORMAT PARAMETER                                           │
+│                                                            │
+│ Research found these format options:                       │
+│                                                            │
+│ [x] json   - Structured JSON response                      │
+│ [x] svg    - Vector logo format                            │
+│ [x] png    - Raster logo format                            │
+│ [ ] raw    - Raw API response (advanced)                   │
+│                                                            │
+│ Which formats should we support?                           │
+└────────────────────────────────────────────────────────────┘
 ```
 
-**Question 6: Required Parameters**
+#### Continuous Parameters (Test Strategy)
 ```
-AskUserQuestion(
-  question="Which parameters are REQUIRED (cannot work without)?",
-  options=[
-    // Based on researched SDK parameters
-    {"value": "prompt_only", "label": "Just the prompt/message"},
-    {"value": "prompt_model", "label": "Prompt + model selection"},
-    {"value": "prompt_model_config", "label": "Prompt + model + configuration"},
-    {"value": "full_config", "label": "Full configuration required"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ QUALITY PARAMETER                                          │
+│                                                            │
+│ Research found: quality is a continuous range 1-100        │
+│                                                            │
+│ How should we TEST this parameter?                         │
+│                                                            │
+│ [ ] All values (100 tests - comprehensive but slow)        │
+│ [x] Boundary (1, 50, 100 - 3 tests)                        │
+│ [ ] Sample (1, 25, 50, 75, 100 - 5 tests)                  │
+│ [ ] Custom values: ____                                    │
+│                                                            │
+│ Your testing strategy affects test count.                  │
+└────────────────────────────────────────────────────────────┘
 ```
 
-**Question 7: Optional Parameters**
+#### Boolean Parameters (Enable/Disable)
 ```
-AskUserQuestion(
-  question="Which optional parameters should be supported?",
-  options=[
-    // From research: discovered optional parameters
-    {"value": "temperature", "label": "temperature (creativity control)"},
-    {"value": "max_tokens", "label": "maxTokens (response length)"},
-    {"value": "system_prompt", "label": "system (system prompt)"},
-    {"value": "tools", "label": "tools (function calling)"},
-    {"value": "all_standard", "label": "All standard AI parameters"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ INCLUDE_COLORS PARAMETER                                   │
+│                                                            │
+│ Research found: includeColors (boolean, default: true)     │
+│                                                            │
+│ Should we expose this parameter?                           │
+│                                                            │
+│ [x] Yes - Let users toggle it                              │
+│ [ ] No - Use default (true) always                         │
+│ [ ] Hardcode to: ____                                      │
+└────────────────────────────────────────────────────────────┘
 ```
 
-#### C. Dependencies & Integration
+### Phase 2: Feature Questions
+
+Based on discovered features, ask about priorities:
 
-**Question 8: External Services**
 ```
-AskUserQuestion(
-  question="What external services does this endpoint need?",
-  options=[
-    {"value": "ai_only", "label": "AI provider only (OpenAI, Anthropic, etc.)"},
-    {"value": "ai_search", "label": "AI + Search (Brave, Perplexity)"},
-    {"value": "ai_scrape", "label": "AI + Web scraping (Firecrawl)"},
-    {"value": "ai_db", "label": "AI + Database (Supabase)"},
-    {"value": "multiple", "label": "Multiple external services"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ DISCOVERED FEATURES                                        │
+│                                                            │
+│ Research found these features. Mark priorities:            │
+│                                                            │
+│ [x] Basic brand fetch - Get logo, colors, fonts            │
+│ [x] Multiple formats - Support json, svg, png              │
+│ [ ] Webhook callbacks - Async notification (skip for now)  │
+│ [ ] Batch processing - Multiple domains at once            │
+│ [x] Error handling - Graceful degradation                  │
+│                                                            │
+│ Confirm feature scope?                                     │
+└────────────────────────────────────────────────────────────┘
 ```
 
-**Question 9: API Key Handling**
+### Phase 3: Error Handling Questions
+
 ```
-AskUserQuestion(
-  question="How should API keys be handled?",
-  options=[
-    {"value": "server_only", "label": "Server environment variables only"},
-    {"value": "server_header", "label": "Server env + custom header override"},
-    {"value": "client_next", "label": "NEXT_PUBLIC_ client-side keys"},
-    {"value": "all_methods", "label": "All methods (env, header, client)"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ ERROR HANDLING                                             │
+│                                                            │
+│ Research found these error cases in the API:               │
+│                                                            │
+│ - 400: Invalid domain format                               │
+│ - 401: Invalid API key                                     │
+│ - 404: Brand not found                                     │
+│ - 429: Rate limit exceeded                                 │
+│ - 500: Server error                                        │
+│                                                            │
+│ How should we handle rate limits (429)?                    │
+│                                                            │
+│ [x] Retry with exponential backoff                         │
+│ [ ] Return error immediately                               │
+│ [ ] Queue and retry later                                  │
+│ [ ] Custom: ____                                           │
+└────────────────────────────────────────────────────────────┘
 ```
 
-#### D. Error Handling & Edge Cases
+### Phase 4: Deep Research Proposal
+
+After interview, propose additional research:
 
-**Question 10: Error Response Format**
 ```
-AskUserQuestion(
-  question="How should errors be returned?",
-  options=[
-    {"value": "simple", "label": "Simple: {error: string}"},
-    {"value": "detailed", "label": "Detailed: {error, code, details}"},
-    {"value": "ai_sdk", "label": "AI SDK standard format"},
-    {"value": "http_native", "label": "HTTP status codes + body"},
-    {"value": "custom", "label": "Type something else..."}
-  ]
-)
+┌────────────────────────────────────────────────────────────┐
+│ PROPOSED DEEP RESEARCH                                     │
+│                                                            │
+│ Based on your selections, I recommend researching:         │
+│                                                            │
+│ [x] Rate limiting behavior                                 │
+│     Reason: You selected "retry with backoff"              │
+│                                                            │
+│ [x] SVG optimization                                       │
+│     Reason: You selected SVG format                        │
+│                                                            │
+│ [ ] Webhook format                                         │
+│     Reason: You skipped webhook feature                    │
+│                                                            │
+│ Approve these searches? [Y]                                │
+│ Add more: ____                                             │
+│ Skip and proceed: [n]                                      │
+└────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 3: Analysis (Documentation)
-After interview, I will:
-- Synthesize answers into structured document
-- Identify gaps or ambiguities
-- Create preliminary schema based on answers
-- Document all external links and resources
-- Outline test cases from real-world scenarios
+## Question Types Summary
+
+| Discovered Type | Question Type | Example |
+|----------------|---------------|---------|
+| Required param | Confirmation | "Confirm these are understood?" |
+| Enum param | Multi-select | "Which formats to support?" |
+| Continuous range | Test strategy | "How to test 1-100 range?" |
+| Boolean param | Enable/disable | "Expose this parameter?" |
+| Optional feature | Priority | "Include this feature?" |
+| Error case | Handling strategy | "How to handle rate limits?" |
+
+## State Tracking
+
+All decisions are saved to `.claude/api-dev-state.json`:
+
+```json
+{
+  "phases": {
+    "interview": {
+      "status": "complete",
+      "questions": [
+        {
+          "parameter": "format",
+          "type": "enum",
+          "options": ["json", "svg", "png", "raw"],
+          "selected": ["json", "svg", "png"],
+          "timestamp": "..."
+        },
+        {
+          "parameter": "quality",
+          "type": "continuous",
+          "range": [1, 100],
+          "test_strategy": "boundary",
+          "test_values": [1, 50, 100],
+          "timestamp": "..."
+        }
+      ],
+      "decisions": {
+        "format": ["json", "svg", "png"],
+        "quality_testing": "boundary",
+        "quality_values": [1, 50, 100],
+        "rate_limit_handling": "exponential_backoff"
+      }
+    }
+  }
+}
+```
 
 ## Output
 
-Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
+Creates: `.claude/research/[api-name]/interview.md`
 
-**Document Structure:**
 ```markdown
-# API Endpoint: [endpoint-name]
+# Interview: [API Name]
 
 **Date:** [current-date]
-**Interviewed by:** Claude Code
+**Research Sources:** [list from research phase]
 **Status:** Interview Complete
-**Research Sources:** [list of Context7/WebSearch sources]
 
-## 1. Purpose & Context
-[Synthesized understanding of why this exists]
+## Discovered Parameters
 
-## 2. Users & Usage Patterns
-[Who uses it and how]
+| Parameter | Type | Required | Decision |
+|-----------|------|----------|----------|
+| domain | string | Yes | Always required |
+| format | enum | No | json, svg, png |
+| quality | 1-100 | No | Boundary testing: 1, 50, 100 |
 
-## 3. Request Schema (Preliminary)
-[Zod-style schema based on interview]
+## Feature Scope
 
-## 4. Response Schema (Preliminary)
-[Expected response structure]
+| Feature | Included | Reason |
+|---------|----------|--------|
+| Basic fetch | Yes | Core functionality |
+| Multiple formats | Yes | User selected |
+| Webhooks | No | Deferred to v2 |
 
-## 5. Dependencies
-- External Services: [list]
-- API Keys Required: [list]
-- AI Models: [list]
+## Test Strategy
 
-## 6. Interview Responses
-| Question | User Selection | Notes |
-|----------|---------------|-------|
-| Purpose | [selected option] | |
-| Users | [selected option] | |
-| ... | ... | |
+- Enum parameters: Test all selected values
+- Continuous parameters: Boundary testing (3 values)
+- Error cases: 400, 401, 404, 429, 500
+
+## Decisions Summary
 
-## 7. Real-World Scenarios
-### Scenario 1: [Common Use Case]
-**Request:**
-```json
-{example}
-```
-**Response:**
 ```json
-{example}
+{
+  "format": ["json", "svg", "png"],
+  "quality_testing": "boundary",
+  "rate_limit_handling": "exponential_backoff"
+}
 ```
 
-## 8. Edge Cases & Error Handling
-[Identified edge cases and how to handle them]
-
-## 9. Validation Rules
-[What must be validated]
+## Deep Research Approved
 
-## 10. Documentation Links
-- [Official docs from research]
-- [SDK docs from Context7]
-- [Related resources from WebSearch]
+- Rate limiting behavior (for retry logic)
+- SVG optimization (for SVG format)
 
-## 11. Test Cases (To Implement)
-- [ ] Test: [scenario from interview]
-- [ ] Test: [edge case from interview]
-- [ ] Test: [error handling from interview]
+## Open Questions
 
-## 12. Open Questions
-[Any ambiguities to resolve]
+[Any remaining ambiguities]
 ```
 
-## Usage Example
+## Integration with Hooks
+
+The `enforce-interview.py` hook injects these decisions when Claude tries to write implementation:
 
-```bash
-/api-interview generate-css
 ```
+INTERVIEW CONTEXT REMINDER
+
+When implementing, remember user decisions:
+- format: ["json", "svg", "png"] (raw excluded)
+- quality: boundary testing (1, 50, 100)
+- rate limits: exponential backoff
 
-I will:
-1. First complete research (Context7 + WebSearch)
-2. Build structured questions with options from research
-3. Ask all questions using AskUserQuestion with options
-4. Document responses and create the endpoint documentation
+Source: .claude/api-dev-state.json
+```
 
 <claude-commands-template>
-## Interview Guidelines (v1.8.0)
+## Interview Guidelines v3.0
 
-1. **RESEARCH FIRST** - Complete Context7 + WebSearch before ANY questions
-2. **STRUCTURED OPTIONS** - Every question uses AskUserQuestion with options[]
-3. **OPTIONS FROM RESEARCH** - Multiple-choice options come from discovered capabilities
-4. **ALWAYS INCLUDE "Type something else..."** - Let user provide custom input
-5. **ASK ONE AT A TIME** - Wait for response before next question
-6. **DOCUMENT EVERYTHING** - Capture ALL selections and custom inputs
+1. **Questions FROM Research** - Never use generic templates
+2. **Parameter-Specific** - Each discovered param gets appropriate question
+3. **Test Strategy for Continuous** - Ask how to test ranges
+4. **Track Decisions** - Save everything to state file
+5. **Propose Deep Research** - Based on selections
+6. **No Skipped Parameters** - Every discovered param must have a decision
 
-## Question Format Checklist
+## Question Generation Rules
 
-Before asking each question:
-- [ ] Is research complete?
-- [ ] Are options based on research findings?
-- [ ] Does it use AskUserQuestion with options parameter?
-- [ ] Is there a "Type something else..." option?
-- [ ] Will this help build the schema?
+| If research finds... | Then ask... |
+|---------------------|-------------|
+| Enum with 3+ options | Multi-select: which to support |
+| Continuous range | Test strategy: all/boundary/sample |
+| Boolean param | Enable/disable/hardcode |
+| Optional feature | Include/exclude/defer |
+| Error case | Handling strategy |
 
 ## After Interview
 
-- Read interview document before implementing
-- Refer to it during TDD cycles
-- Update it if requirements change
-- Use it for code review context
+- Decisions saved to state file
+- Decisions injected during implementation via hook
+- Consistency between interview answers and code enforced
 </claude-commands-template>