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

package/commands/api-verify.md

@@ -0,0 +1,231 @@
+# API Verify - Implementation Verification (Phase 9) v3.0
+
+**Usage:** `/api-verify [endpoint-name]`
+
+**Purpose:** Manually trigger Phase 9 verification - re-research documentation and compare to implementation to catch memory-based errors.
+
+## When to Use
+
+- After tests pass (TDD Green complete)
+- Before proceeding to Refactor phase
+- When unsure if implementation matches documentation
+- After significant time has passed since initial research
+
+## Verification Process
+
+### Step 1: Re-Read Original Documentation
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ RE-RESEARCHING DOCUMENTATION                               │
+│                                                            │
+│ Fetching current documentation for: [endpoint-name]        │
+│                                                            │
+│ Sources:                                                   │
+│ - Context7: [library-name]                                 │
+│ - Official docs: [URL]                                     │
+│ - Cached research: .claude/research/[api]/CURRENT.md       │
+│                                                            │
+│ Freshness: [X days old]                                    │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 2: Feature-by-Feature Comparison
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ IMPLEMENTATION VERIFICATION                                │
+│                                                            │
+│ Comparing documentation to implementation:                 │
+│                                                            │
+│ │ Feature         │ In Docs │ Implemented │ Status        │
+│ ├─────────────────┼─────────┼─────────────┼───────────────│
+│ │ domain param    │ ✓       │ ✓           │ ✅ Match      │
+│ │ format param    │ 4 opts  │ 3 opts      │ ⚠️ Missing    │
+│ │ quality range   │ 1-100   │ 1-100       │ ✅ Match      │
+│ │ size param      │ ✓       │ ✗           │ ⚠️ Missing    │
+│ │ webhook support │ ✓       │ ✗           │ ℹ️ Intentional │
+│ │ batch mode      │ ✓       │ ✗           │ ℹ️ Intentional │
+│                                                            │
+│ MATCHES: 2                                                 │
+│ MISSING: 2                                                 │
+│ INTENTIONAL OMISSIONS: 2                                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Gap Analysis
+
+For each discrepancy:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ GAP #1: format parameter                                   │
+│                                                            │
+│ Documentation says: ["json", "svg", "png", "raw"]          │
+│ Implementation has:  ["json", "svg", "png"]                │
+│                                                            │
+│ Missing: "raw" format                                      │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add "raw" format support                         │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────┐
+│ GAP #2: size parameter                                     │
+│                                                            │
+│ Documentation says: size parameter exists (16-4096)        │
+│ Implementation has:  not implemented                       │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add size parameter                               │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 4: Loop Back or Proceed
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ VERIFICATION SUMMARY                                       │
+│                                                            │
+│ Gaps to fix: 2                                             │
+│ Intentional omissions: 2                                   │
+│                                                            │
+│ DECISION:                                                  │
+│                                                            │
+│ [x] Fix gaps → Return to TDD Red (write tests for gaps)    │
+│ [ ] Skip all → Document as omissions, proceed to Refactor  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## State File Updates
+
+```json
+{
+  "phases": {
+    "verify": {
+      "status": "complete",
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": [
+        {
+          "feature": "webhook support",
+          "reason": "User declined in interview",
+          "documented_at": "..."
+        },
+        {
+          "feature": "batch mode",
+          "reason": "Out of scope for v1",
+          "documented_at": "..."
+        }
+      ],
+      "re_research_done": true,
+      "completed_at": "..."
+    }
+  }
+}
+```
+
+## Verification Report
+
+Creates: `.claude/research/[api-name]/verification.md`
+
+```markdown
+# Verification Report: [API Name]
+
+**Date:** [current-date]
+**Implementation File:** src/app/api/v2/[endpoint]/route.ts
+**Test File:** src/app/api/v2/[endpoint]/__tests__/[endpoint].api.test.ts
+
+## Documentation Sources Re-Checked
+
+| Source | URL | Checked |
+|--------|-----|---------|
+| Official docs | [URL] | ✓ |
+| Context7 | [library] | ✓ |
+| Cached research | .claude/research/[api]/CURRENT.md | ✓ |
+
+## Feature Comparison
+
+| Feature | In Docs | Implemented | Status |
+|---------|---------|-------------|--------|
+| domain param | ✓ | ✓ | ✅ Match |
+| format param | 4 options | 3 options | ⚠️ Fixed |
+| size param | ✓ | ✓ | ⚠️ Fixed |
+| webhook | ✓ | ✗ | ℹ️ Intentional |
+
+## Gaps Fixed
+
+1. **format parameter** - Added "raw" format support
+   - Test added: test/format-raw.test.ts:15
+   - Implementation: route.ts:45
+
+2. **size parameter** - Added size validation
+   - Test added: test/size-param.test.ts:10
+   - Implementation: route.ts:52
+
+## Intentional Omissions
+
+1. **webhook support**
+   - Reason: User declined in interview (Phase 3)
+   - Decision recorded: api-dev-state.json
+   - May add in v2
+
+2. **batch mode**
+   - Reason: Out of scope for initial release
+   - Documented for future consideration
+
+## Verification Result
+
+- **Status:** PASSED
+- **All documented features accounted for**
+- **Ready for Refactor phase**
+```
+
+## Hook Integration
+
+This command is normally triggered automatically by `verify-after-green.py` hook after tests pass.
+
+Manual invocation is useful when:
+- Hook was skipped or didn't trigger
+- Want to re-verify after changes
+- Research is stale and needs refresh
+
+## Workflow Position
+
+```
+Phase 7: TDD Red (write tests)
+    │
+    ▼
+Phase 8: TDD Green (implementation)
+    │
+    ▼
+Phase 9: VERIFY ← /api-verify triggers this
+    │
+    ├─► Gaps found? → Loop back to Phase 7
+    │
+    └─► All verified → Proceed to Phase 10 (Refactor)
+```
+
+<claude-commands-template>
+## Verification Guidelines
+
+1. **Re-read, don't remember** - Fresh fetch of docs every time
+2. **Feature-by-feature** - Systematic comparison
+3. **Document omissions** - Intentional != forgotten
+4. **Loop back for gaps** - Return to TDD Red if fixes needed
+5. **Update state file** - Track everything
+6. **Create verification report** - Audit trail
+
+## Common Gaps to Check
+
+- Parameter counts match?
+- Enum options complete?
+- Range boundaries correct?
+- Error codes handled?
+- Optional features accounted for?
+- Default values match docs?
+</claude-commands-template>