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

package/commands/api-research.md

@@ -1,77 +1,154 @@
-# API Research - Documentation Discovery & Schema Extraction
+# API Research - Adaptive Documentation Discovery v3.0
 
 **Usage:** `/api-research [library-or-service-name]`
 
-**Purpose:** Automatically research external APIs, SDKs, and libraries to discover ALL available parameters, options, and features.
+**Purpose:** Research external APIs and SDKs using an adaptive, propose-approve flow (not shotgun searches).
 
-## What This Command Does
+## Key Principle: Adaptive Research
 
-1. **Searches for Official Documentation**
-   - Official API docs
-   - SDK/library documentation
-   - GitHub repositories
-   - npm package pages (if applicable)
+**NOT shotgun research** - We don't blindly run 20 searches.
 
-2. **Extracts Complete Schemas**
-   - All request parameters (required + optional)
-   - All response fields
-   - Type definitions
-   - Validation rules
-   - Default values
+**Adaptive flow:**
+1. Run 2-3 initial searches
+2. Summarize findings
+3. PROPOSE additional searches based on context
+4. User approves/modifies proposals
+5. Execute approved searches
+6. Repeat until complete
 
-3. **Discovers Hidden Features**
-   - Undocumented parameters (from source code)
-   - Advanced configuration options
-   - Beta/experimental features
-   - Deprecated options to avoid
+## Research Phases
 
-4. **Documents Integration Requirements**
-   - Required environment variables
-   - API key setup
-   - Rate limits and quotas
-   - Pricing/cost information
-   - Version compatibility
+### Phase 1: Initial Discovery (Automatic)
 
-## Research Process
+Run 2-3 targeted searches:
+```
+- Context7: "[library-name]" (if SDK/library)
+- WebSearch: "[name] official documentation"
+- WebSearch: "site:[domain] api reference" (if known domain)
+```
 
-### Step 1: Find Official Sources
+Present initial summary:
 ```
-- Web search for "[library-name] documentation"
-- Check npm registry for package info
-- Find GitHub repository
-- Look for TypeScript definitions
-- Search for community resources
+┌────────────────────────────────────────────────────────────┐
+│ INITIAL RESEARCH: [library-name]                           │
+│                                                            │
+│ │ Source              │ Status                             │
+│ ├─────────────────────┼────────────────────────────────────│
+│ │ Official docs       │ ✓ Found: [URL]                     │
+│ │ API Reference       │ ✓ REST v2 documented               │
+│ │ Auth method         │ ✓ Bearer token / API key           │
+│ │ TypeScript types    │ ? Not confirmed                    │
+│ │ npm package         │ ? Not searched                     │
+│                                                            │
+│ Discovered parameters: 5 required, 12 optional             │
+│                                                            │
+│ Proceed to interview? [Y]                                  │
+│ Search more first? [n] → What? ____                        │
+└────────────────────────────────────────────────────────────┘
 ```
 
-### Step 2: Deep Dive into Documentation
+### Phase 2: Deep Research (Proposed)
+
+After interview, PROPOSE targeted searches based on user's selections:
+
 ```
-- Read API reference pages
-- Review SDK documentation
-- Check TypeScript type definitions (.d.ts files)
-- Look at example code
-- Find changelog for recent changes
+┌────────────────────────────────────────────────────────────┐
+│ PROPOSED DEEP RESEARCH                                     │
+│                                                            │
+│ Based on interview answers, I recommend researching:       │
+│                                                            │
+│ [x] Error response format                                  │
+│     Reason: You selected "comprehensive error handling"    │
+│                                                            │
+│ [x] Rate limiting behavior                                 │
+│     Reason: You selected "short cache" / high frequency    │
+│                                                            │
+│ [ ] Webhook support                                        │
+│     Reason: You didn't select async/webhook features       │
+│                                                            │
+│ [x] SVG optimization options                               │
+│     Reason: You selected SVG output format                 │
+│                                                            │
+│ [x] Batch processing                                       │
+│     Reason: You mentioned "multiple domains at once"       │
+│                                                            │
+│ Approve these searches? [Y]                                │
+│ Add more: ____                                             │
+│ Skip and proceed: [n]                                      │
+└────────────────────────────────────────────────────────────┘
 ```
 
-### Step 3: Source Code Analysis
+### Phase 3: Execute Approved Searches
+
+Only run searches that were explicitly approved:
+- Track which searches were proposed vs approved vs skipped
+- Log everything to state file for transparency
+
+```json
+{
+  "research_deep": {
+    "proposed_searches": [
+      "error response format",
+      "rate limiting behavior",
+      "webhook support",
+      "SVG optimization options",
+      "batch processing"
+    ],
+    "approved_searches": [
+      "error response format",
+      "rate limiting behavior",
+      "SVG optimization options",
+      "batch processing"
+    ],
+    "skipped_searches": [
+      "webhook support"
+    ]
+  }
+}
 ```
-- Review actual implementation code
-- Check for undocumented parameters
-- Find default values in source
-- Identify validation logic
-- Discover error cases
+
+## Research Caching & Freshness
+
+Research is cached in `.claude/research/[api-name]/`:
+
+```
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md    # Timestamped snapshot
+│   ├── 2025-12-08_deep.md       # Deep research after interview
+│   └── CURRENT.md               # Latest (copy or symlink)
+├── vercel-ai-sdk/
+│   ├── providers/               # Complex APIs get subfolders
+│   │   ├── openai.md
+│   │   ├── anthropic.md
+│   │   └── groq.md
+│   └── CURRENT.md
+└── index.json                   # Catalog with freshness
+```
+
+### Freshness Tracking
+
+```json
+{
+  "brandfetch": {
+    "last_updated": "2025-12-08",
+    "current_file": "brandfetch/CURRENT.md",
+    "days_old": 0,
+    "parameters_discovered": 7,
+    "source_urls": ["https://docs.brandfetch.com"]
+  }
+}
 ```
 
-### Step 4: Test & Verify
+**Freshness Rule:** If research is >7 days old when referenced:
 ```
-- Check what parameters are actually used
-- Verify parameter names and types
-- Test edge cases
-- Document observed behavior
+⚠️ Research for "brandfetch" is 15 days old.
+Re-research before using? [Y/n]
 ```
 
 ## Output Format
 
-Creates: `/src/v2/docs/research/[library-name].md`
+Creates: `.claude/research/[library-name]/CURRENT.md`
 
 ```markdown
 # Research: [Library/Service Name]
@@ -79,6 +156,7 @@ Creates: `/src/v2/docs/research/[library-name].md`
 **Date:** [current-date]
 **Version:** [version-number]
 **Status:** Research Complete
+**Freshness:** 0 days (valid for 7 days)
 
 ## 1. Official Documentation Links
 - Main docs: [URL]
@@ -112,155 +190,49 @@ Creates: `/src/v2/docs/research/[library-name].md`
 |-----------|------|---------|-------------|-------|
 | [name] | [type] | [default] | [desc] | [notes] |
 
-### Zod Schema (Preliminary)
-```typescript
-const RequestSchema = z.object({
-  // Required
-  requiredParam: z.string().min(1),
-
-  // Optional with defaults
-  optionalParam: z.string().default('default-value'),
-
-  // Enums
-  mode: z.enum(['option1', 'option2']).default('option1'),
-
-  // Nested objects
-  config: z.object({
-    setting: z.boolean().default(true),
-  }).optional(),
-});
-```
+### Continuous Parameters (for test strategy)
+| Parameter | Type | Range | Suggested Test Values |
+|-----------|------|-------|----------------------|
+| quality | number | 1-100 | 1, 50, 100 (boundary) |
+| timeout | number | 1000-30000 | 1000, 15000, 30000 |
 
 ## 4. Complete Response Schema
 ### Success Response
-```typescript
-interface SuccessResponse {
-  [field]: [type]; // [description]
-}
-```
+[TypeScript interface]
 
 ### Error Response
-```typescript
-interface ErrorResponse {
-  error: string;
-  code?: string;
-  details?: unknown;
-}
-```
-
-### Zod Schema (Preliminary)
-```typescript
-const ResponseSchema = z.object({
-  // Response fields
-});
-```
+[TypeScript interface with error codes]
 
 ## 5. Features & Capabilities
-### Core Features
-- [Feature 1]: [description]
-- [Feature 2]: [description]
-
-### Advanced Features
-- [Advanced 1]: [description + how to enable]
-- [Advanced 2]: [description + how to enable]
+### Core Features (Discovered)
+- [x] [Feature 1]: [description]
+- [x] [Feature 2]: [description]
 
-### Experimental/Beta Features
-- [Beta feature]: [description + stability notes]
+### Features NOT Implemented (Intentional)
+- [ ] [Feature]: [reason for exclusion]
 
 ## 6. Limitations & Constraints
 - Rate limits: [details]
 - Size limits: [details]
 - Timeout: [details]
-- Quotas: [details]
-- Costs: [details]
-
-## 7. Integration Notes
-### Vercel AI SDK Integration
-[If using AI SDK, document integration patterns]
-
-### Error Handling
-[Common errors and how to handle]
-
-### Best Practices
-- [Practice 1]
-- [Practice 2]
-
-## 8. Code Examples
-### Basic Usage
-```typescript
-[minimal example]
-```
-
-### Advanced Usage
-```typescript
-[example with optional parameters]
-```
-
-### Error Handling
-```typescript
-[example with try/catch]
-```
 
-## 9. Testing Considerations
-- [ ] Test basic success case
-- [ ] Test all optional parameters
-- [ ] Test validation failures
-- [ ] Test rate limiting
-- [ ] Test timeout scenarios
+## 7. Testing Considerations
+- [ ] Test boundary values for continuous params
+- [ ] Test all enum values
 - [ ] Test error responses
+- [ ] Test rate limiting behavior
 
-## 10. Version History & Changes
-[Notable changes in recent versions]
+## 8. Research Trail
+### Searches Performed
+| Search | Tool | Found |
+|--------|------|-------|
+| "[name] documentation" | WebSearch | ✓ |
+| "[name]" | Context7 | ✓ |
 
-## 11. Related Resources
-- [Community examples]
-- [Blog posts]
-- [Stack Overflow discussions]
-- [Alternative libraries]
+### Proposed but Skipped
+- "webhook support" - User declined, not needed
 ```
 
-## Usage Examples
-
-### Research an AI SDK
-```bash
-/api-research vercel-ai-sdk-generateText
-```
-
-### Research an External API
-```bash
-/api-research firecrawl-api
-```
-
-### Research a Library
-```bash
-/api-research anthropic-sdk
-```
-
-## Research Workflow
-
-1. **Execute command**: `/api-research [name]`
-2. **I search and analyze**: Web search → Documentation → Source code
-3. **Document everything**: Create comprehensive research doc
-4. **Review together**: You verify accuracy and completeness
-5. **Use in implementation**: Reference during TDD cycle
-
-## Why This Matters
-
-Without thorough research:
-- ❌ Miss optional parameters that users need
-- ❌ Don't test edge cases properly
-- ❌ Implement wrong validation rules
-- ❌ Create brittle integrations
-
-With thorough research:
-- ✅ Know ALL available options
-- ✅ Test comprehensively
-- ✅ Proper validation
-- ✅ Robust implementation
-- ✅ Better documentation
-
----
-
 ## Research-First Schema Design (MANDATORY)
 
 ### The Anti-Pattern: Schema-First Development
@@ -271,86 +243,89 @@ With thorough research:
 - ❌ Say "I think it supports..." without verification
 - ❌ Build schemas from memory instead of documentation
 
-**Real Example of Failure:**
-- User asked: "What providers does Vercel AI Gateway support?"
-- AI answered from memory: "Groq not in gateway"
-- Reality: Groq has 4 models in the gateway (Llama variants)
-- Root cause: No research was done before answering
-
 ### The Correct Pattern: Research-First
 
 **ALWAYS DO THIS:**
 
-**Step 1: Research the Source of Truth**
-- Use Context7 (`mcp__context7__resolve-library-id` + `get-library-docs`) for SDK docs
-- Use WebSearch for official provider documentation
-- Query APIs directly when possible (don't assume)
-- Check GitHub repositories for current implementation
-
-**Step 2: Build Schema FROM Research**
-- Interface fields emerge from discovered capabilities
-- Every field has a source (docs, SDK types, API response)
-- Don't guess - verify each capability
-- Document where each field came from
+1. **Research the Source of Truth**
+   - Use Context7 for SDK docs
+   - Use WebSearch for official docs
+   - Check GitHub for current implementation
 
-**Step 3: Verify with Actual Calls**
-- Test capabilities before marking them supported
-- Investigate skipped tests - they're bugs, not features
-- No "should work" - prove it works
-- All tests must pass, not be skipped
+2. **Build Schema FROM Research**
+   - Interface fields emerge from discovered capabilities
+   - Every field has a source (docs, SDK types, API response)
+   - Don't guess - verify each capability
 
-### Mandatory Checklist Before Answering ANY External API Question
+3. **Verify with Phase 9**
+   - After implementation, re-research
+   - Compare docs to implementation
+   - Fix gaps or document intentional omissions
 
-Before responding to questions about APIs, SDKs, or external services:
+## Research Query Tracking
 
-```
-[ ] Did I use Context7 to get current documentation?
-[ ] Did I use WebSearch for official docs?
-[ ] Did I verify the information is current (not training data)?
-[ ] Am I stating facts from research, not memory?
-[ ] Have I cited my sources?
-```
-
-### Research Query Tracking
-
-All research is now tracked in `.claude/api-dev-state.json`:
+All research is tracked in `.claude/api-dev-state.json`:
 
 ```json
 {
   "research_queries": [
     {
-      "timestamp": "2025-12-07T...",
+      "timestamp": "2025-12-08T...",
       "tool": "WebSearch",
-      "query": "Vercel AI Gateway Groq providers",
-      "terms": ["vercel", "gateway", "groq", "providers"]
+      "query": "Brandfetch API documentation",
+      "terms": ["brandfetch", "api", "documentation"]
     },
     {
-      "timestamp": "2025-12-07T...",
+      "timestamp": "2025-12-08T...",
       "tool": "mcp__context7__get-library-docs",
-      "library": "@ai-sdk/gateway",
-      "terms": ["@ai-sdk/gateway"]
+      "library": "brandfetch",
+      "terms": ["brandfetch"]
+    }
+  ],
+  "phases": {
+    "research_initial": {
+      "status": "complete",
+      "sources": [...],
+      "summary_approved": true
+    },
+    "research_deep": {
+      "status": "complete",
+      "proposed_searches": [...],
+      "approved_searches": [...],
+      "skipped_searches": [...]
     }
-  ]
+  }
 }
 ```
 
-This allows verification that specific topics were actually researched before answering.
+## Usage Examples
+
+### Research with full flow
+```bash
+/api-research brandfetch
+# → Initial search (2-3 queries)
+# → Present summary, ask to proceed
+# → Interview happens (separate phase)
+# → Propose deep research based on interview
+# → User approves/modifies
+# → Execute approved searches
+# → Cache results with freshness tracking
+```
 
 <claude-commands-template>
 ## Research Guidelines
 
-1. **Read actual code** - TypeScript definitions reveal truth
-2. **Test assumptions** - Verify parameters actually work
-3. **Document sources** - Track ALL links for future reference
-4. **Check versions** - Note version-specific features
-5. **Find examples** - Real code > documentation
-6. **Look for gotchas** - Common mistakes, limitations, bugs
+1. **Start minimal** - 2-3 searches, not 20
+2. **Propose before executing** - User controls depth
+3. **Track everything** - State file logs all searches
+4. **Cache with freshness** - 7-day validity
+5. **Cite sources** - Every claim has a URL
+6. **Distinguish proposed vs approved** - Transparency
 
 ## Integration with API Development
 
-After research:
-- Use in `/api-interview` to ask informed questions
-- Reference in `/api-create` for schema creation
-- Base tests on discovered parameters
-- Update if API changes
+- Phase 2 of `/api-create` uses this for initial research
+- Phase 4 uses adaptive proposal flow
+- Phase 9 (Verify) triggers re-research
+- Freshness check prevents stale data
 </claude-commands-template>