@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/debug-fe-be-integration/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: debug-fe-be-integration
+description: >
+  Diagnose and fix frontend↔backend contract failures by tracing requests,
+  server logs, validation, auth, and responses on both sides. Use for API
+  4xx/5xx, mismatched payloads, or "frontend and backend disagree". One layer
+  → debug-error.
+license: MIT
+effort: high
+---
+
+# Frontend-Backend Integration Debug Skill
+
+**Degree of freedom: MIXED.** Which side is wrong `[HIGH freedom]`;
+trace-both-sides probes `[LOW freedom — run exactly]`.
+
+Systematic approach to debugging frontend-backend integration issues by analyzing backend
+logs, production errors, and source code to identify root causes and fix both sides.
+
+## How to reason
+
+1. **Observe** — status, payload, validation error, both logs
+2. **Interpret** — FE omitted a field vs BE schema drifted vs auth/CORS
+3. **Classify** — missing-param / type / 404 / 401 / 500 / CORS
+4. **Severity** — 500 on a write path outranks a cosmetic 422 message
+
+## Worked example
+
+> **Observe:** FE `GET /api/reports` → 500; BE log `ZodError: expected string, received undefined` on `year`.
+> **Interpret:** FE omitted `year`; BE schema required it with no default.
+> **Classify:** missing-param — fix FE call and add a clear BE 422/default.
+> **Verify:** same request returns 200 with the year bound; both sides updated.
+
+## Self-critique before reporting
+
+- **Both sides read** — FE call and BE schema/logs, not one side guessed
+- **Contract named** — status + payload field, not "they disagree"
+- **Fix matches class** — 404 is not patched as a Zod default
+- **Right owner** — single-layer crash → `debug-error`; proactive contract audit → `audit-fe-api`
+
+---
+
+## Step 0: Auto-Detect Stack
+
+Before debugging, discover the project's architecture.
+
+### 0a. Detect Frontend Framework
+
+Read `package.json` and look for:
+
+| Signal | Framework |
+|--------|-----------|
+| `next` | Next.js |
+| `nuxt` | Nuxt |
+| `@remix-run/react` | Remix |
+| `@sveltejs/kit` | SvelteKit |
+| `vite` + `react` | Vite React SPA |
+| `@angular/core` | Angular |
+
+### 0b. Detect Backend Framework
+
+```
+Glob: **/app/api/**/route.ts → Next.js App Router
+Glob: **/pages/api/**/*.ts → Next.js Pages Router
+Glob: **/server/api/**/*.ts → Nuxt server
+Glob: **/src/routes/**/*.ts → Express/Hono/Fastify
+Glob: **/src/app.ts or **/src/index.ts → Node backend entry
+Glob: **/main.py or **/app.py → Python backend
+Glob: **/main.go → Go backend
+```
+
+### 0c. Detect API Style and Validation
+
+| Signal | Technology |
+|--------|-----------|
+| `@trpc/server` | tRPC (type-safe, no REST audit needed) |
+| `graphql` or `@apollo/server` | GraphQL |
+| `zod` in BE dependencies | Zod validation |
+| `joi` in BE dependencies | Joi validation |
+| `yup` in BE dependencies | Yup validation |
+| `class-validator` | NestJS-style validation |
+| `pydantic` | Python Pydantic validation |
+
+### 0d. Find Route and Controller Patterns
+
+```
+Grep: pattern "router\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Express-style
+Grep: pattern "app\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Hono/Express
+Grep: pattern "export (async function |const )(GET|POST|PATCH|PUT|DELETE)" glob "**/route.ts" — Next.js
+Grep: pattern "defineEventHandler" glob "*.{ts,js}" — Nuxt/H3
+```
+
+### 0e. Record Discovery
+
+```
+STACK DISCOVERY:
+- Frontend: [framework + version]
+- Backend: [framework + version]
+- API style: [REST / GraphQL / tRPC]
+- Validation: [Zod / Joi / Yup / Pydantic / none]
+- Route files: [pattern and locations]
+- Controller files: [pattern and locations]
+- Schema files: [pattern and locations]
+```
+
+---
+
+## Step 1: Research Debugging Patterns
+
+### 1a. Firecrawl — Integration Debugging
+
+Search the framework and validation library as written — recognizing the name is not knowing its current API or error shape.
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<FE_FRAMEWORK> <BE_FRAMEWORK> API integration debugging best practices [current year]",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Additional targeted searches:
+
+| Topic | Query |
+|-------|-------|
+| Validation errors | `<VALIDATION_LIB> error handling API response best practices` |
+| CORS issues | `<BE_FRAMEWORK> CORS configuration debugging` |
+| Type mismatches | `TypeScript API type safety frontend backend shared types` |
+
+### 1b. Context7 — Framework Docs
+
+```json
+context7:resolve-library-id
+{
+ "libraryName": "<VALIDATION_LIB>",
+ "query": "error handling error messages custom errors"
+}
+```
+
+---
+
+## Step 2: Gather Error Evidence
+
+### 2a. Check Sentry for Production Errors
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "query": "API integration errors 4xx 5xx validation from the last 7 days",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "limit": 25
+}
+```
+
+If the project has separate FE and BE Sentry projects, check both:
+- FE project: network errors, unhandled rejections from API calls
+- BE project: validation errors, unhandled exceptions, 500s
+
+### 2b. Read Backend Terminal Logs
+
+Read the output of the terminal running the backend (`npm run dev` or equivalent) — in Cursor, `terminals/*.txt`; in Claude Code, the shell or log file you started it from.
+
+Look for errors in the last 3-5 minutes:
+- `4xx` errors (400, 401, 403, 404, 422)
+- `5xx` errors (500, 502, 503)
+- `ZodError` / `ValidationError` — validation failures
+- `AppError` / custom error classes
+- Stack traces
+- Warning messages
+
+### 2c. Categorize Errors Found
+
+| Category | Log Pattern | Root Cause |
+|----------|-------------|------------|
+| Missing parameter | `ZodError: expected string, received undefined` | FE not sending required param |
+| Wrong type | `ZodError: invalid_type` | FE sending wrong type |
+| Endpoint not found | `404 /api/...` | FE calling non-existent endpoint |
+| Auth error | `401 Unauthorized` | Missing or invalid token |
+| Permission error | `403 Forbidden` | User lacks permission |
+| Validation error | `422 Unprocessable` | Invalid request body |
+| Server error | `500 Internal` | Backend bug |
+| CORS error | `CORS policy` | Missing CORS configuration |
+
+---
+
+## Step 3: Trace Errors to Source Code
+
+### 3a. Map Errors to Endpoints
+
+For each error found, use `Grep` to locate:
+
+**Frontend call:**
+```
+Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,tsx,js,jsx}"
+```
+
+**Backend route:**
+```
+Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,js,py,go,rb}" — in backend source
+```
+
+**Validation schema:**
+```
+Grep: pattern "z\.object|z\.string|z\.number" in the controller/route file
+SemanticSearch: "validation schema for <ENDPOINT>" target: [backend directory]
+```
+
+### 3b. Read the Full Chain
+
+For each error, read the complete request chain:
+
+1. **Frontend call** — Read the file making the API call (service, hook, or component)
+2. **API client config** — Read the axios/fetch interceptor configuration
+3. **Backend route** — Read the route handler
+4. **Backend controller** — Read the controller/service logic
+5. **Validation schema** — Read the Zod/Joi/Yup schema for the endpoint
+6. **Database query** — Read the DB query (if the error is data-related)
+
+### 3c. Verify Data State with Supabase MCP
+
+If the error might be data-related:
+
+```json
+supabase:execute_sql
+{
+ "query": "SELECT * FROM <TABLE> WHERE <CONDITION> LIMIT 5"
+}
+```
+
+Check:
+- Does the data the FE expects actually exist?
+- Are enum values correct?
+- Are foreign key relationships intact?
+- Does the RLS policy allow access for this user?
+
+---
+
+## Step 4: Generate Fix Recommendations
+
+### 4a. Frontend Fixes
+
+For each error, provide:
+
+```markdown
+### Issue: [Endpoint] — [Error Type]
+
+**Current FE Call:**
+[show the actual code from Grep results]
+
+**Correct FE Call:**
+[show the fixed code]
+
+**Why:** [explanation of required parameter/type/format]
+
+**Files to Update:** [list specific files]
+```
+
+### 4b. Backend Enhancements
+
+For each error, consider backend improvements — as recommendations in the report. Apply the fix for the contract failure at hand; the robustness enhancements ship only when the user asks, and every edit is surgical.
+
+```markdown
+### Backend Enhancement: [Endpoint]
+
+**Current Behavior:** Returns 500 with cryptic validation error
+
+**Recommended Enhancement:**
+- Add default value for optional params
+- Add clear error message for required params
+- Add type coercion where appropriate
+- Return helpful 422 instead of 500
+```
+
+Example backend enhancement pattern:
+
+```typescript
+// Before: bare schema, cryptic error on missing param
+const schema = z.object({
+ year: z.string(),
+});
+
+// After: defaults, coercion, clear errors
+const schema = z.object({
+ year: z.string({
+ required_error: "year is required (format: YYYY)"
+ }).default(() => new Date().getFullYear().toString()),
+ page: z.coerce.number().default(1).int().positive(),
+ limit: z.coerce.number().default(10).int().max(100),
+});
+```
+
+---
+
+## Step 5: Backend Robustness Checklist
+
+### Input Validation
+- [ ] All required params have clear error messages
+- [ ] Default values for optional params with sensible defaults
+- [ ] Type coercion where appropriate (string to number)
+- [ ] Range validation (dates, numbers)
+- [ ] Format validation (email, UUID, date strings)
+
+### Error Handling
+- [ ] Catch and wrap database errors
+- [ ] Provide actionable error messages (not "Internal Server Error")
+- [ ] Log errors with context (userId, endpoint, params)
+- [ ] Do not expose internal details to client (stack traces, SQL)
+
+### API Contract Consistency
+- [ ] Response shape is consistent (`{ data }` or `{ error }`)
+- [ ] Status codes are correct (200 success, 201 create, 204 delete)
+- [ ] Pagination format is consistent across all list endpoints
+- [ ] Date formats are consistent (ISO 8601)
+- [ ] Error response shape is consistent
+
+---
+
+## Output Template
+
+```markdown
+## Frontend-Backend Integration Debug Report
+
+**Analyzed:** [timestamp range]
+**Frontend:** [framework]
+**Backend:** [framework]
+**API style:** [REST/GraphQL/tRPC]
+
+---
+
+### Production Errors (Sentry)
+
+| Endpoint | Error | Events (7d) | Root Cause |
+|----------|-------|-------------|------------|
+| [endpoint] | [error msg] | [count] | [FE/BE/Data] |
+
+---
+
+### Backend Log Errors
+
+| Endpoint | Method | Status | Error Type | Root Cause |
+|----------|--------|--------|------------|------------|
+| `/api/...` | GET | 500 | ZodError | Missing `year` param |
+| `/api/...` | GET | 404 | Not Found | Endpoint not implemented |
+
+---
+
+### Critical Issues (Must Fix)
+
+#### 1. [Endpoint] — [Status Code]
+- **Error:** [error message]
+- **Root Cause:** [explanation]
+- **Frontend Fix:** [what FE needs to change, with code]
+- **Backend Enhancement:** [optional BE improvement, with code]
+- **Files:** FE: [path], BE: [path]
+
+---
+
+### Warnings (Should Fix)
+
+#### 1. [Issue description]
+- **Impact:** [what happens if not fixed]
+- **Recommendation:** [how to fix]
+
+---
+
+### Backend Enhancements (Robustness)
+
+#### 1. [Enhancement description]
+- **Current:** [current behavior]
+- **Recommended:** [better approach]
+- **Benefit:** [why this helps]
+
+---
+
+### Research Findings Applied
+- [Pattern from research]: [how it applies]
+- [Best practice]: [gap identified]
+
+---
+
+### Summary Table
+
+| Endpoint | Issue | Fix Required | Priority |
+|----------|-------|--------------|----------|
+| `/api/...` | Missing param | Frontend | HIGH |
+| `/api/...` | No error handling | Both | MEDIUM |
+| `/api/...` | Endpoint 404 | Remove or implement | LOW |
+
+---
+
+### Next Steps
+
+1. [ ] Frontend fixes: [action items with files]
+2. [ ] Backend enhancements: [action items with files]
+3. [ ] Re-test: [verification steps]
+4. [ ] Monitor: Check Sentry after deploy for regression
+```
+
+---
+
+## Common Patterns and Fixes
+
+### Pattern 1: Missing Query Parameter
+
+**Symptom:** `ZodError: expected string, received undefined`
+
+**FE Fix:** Add the missing parameter to the API call.
+
+**BE Fix:** Add a default value or a clear error message.
+
+### Pattern 2: Endpoint Not Found (404)
+
+**Symptom:** `404 /api/endpoint-name`
+
+**Debug steps:**
+1. `Grep` for the endpoint path in backend route files
+2. Check if the endpoint exists under a different name
+3. Check API docs if available
+4. Decide: remove FE call, fix typo, or implement endpoint
+
+### Pattern 3: Service Failure (500)
+
+**Symptom:** `500 Internal Server Error` with no useful message
+
+**Debug steps:**
+1. Read the backend controller for unhandled exceptions
+2. Check if the service handles DB errors gracefully
+3. Check RLS policies if using Supabase (data might be blocked)
+4. Add try/catch with meaningful error responses
+
+### Pattern 4: CORS Error
+
+**Symptom:** `CORS policy: No 'Access-Control-Allow-Origin'`
+
+**Debug steps:**
+1. Check backend CORS configuration
+2. Verify the origin, methods, and headers allowed
+3. Check if credentials mode matches between FE and BE
+
+### Pattern 5: Duplicate / Stale Requests
+
+**Symptom:** Same API called multiple times, or stale data shown
+
+**Debug steps:**
+1. Check if TanStack Query / SWR staleTime is configured
+2. Check if cache invalidation happens after mutations
+3. Check if the queryKey is correct and unique
+4. Check for component re-mount causing refetch
+
+---
+
+## Integration with Other Skills
+
+- **`audit-fe-api`**: Proactive audit from FE code perspective (run first).
+- **`debug-sentry-monitor`**: Triage and fix Sentry errors from production.
+- **`audit-db-schema`**: Verify DB schema matches API expectations.