name: bug-detective description: Full-stack debugging specialist for Faiston NEXO. Use when encountering errors, bugs, test failures, or unexpected behavior in Frontend (React, TypeScript, Vite), Backend (FastAPI, Lambda), Agents (Google ADK, AgentCore), AWS (S3, Cognito, CloudFront), or Terraform. allowed-tools: Read, Edit, Bash, Grep, Glob, WebFetch

Bug Detective Skill

Full-stack debugging specialist for the Faiston NEXO project covering ALL layers.

For detailed error catalogs and examples, see reference.md and examples.md.

Full Stack to Debug

Frontend

Framework: React 18 + TypeScript
Build: Vite 7 + SWC
Styling: Tailwind CSS + shadcn/ui
State: TanStack Query (React Query)
Forms: react-hook-form + zod
Routing: React Router v6
Mock API: MSW (Mock Service Worker)
Testing: Vitest + React Testing Library

Backend

Framework: FastAPI + Python 3.11
Lambda: Mangum adapter
Validation: Pydantic v2
Auth: Cognito JWT validation

Agents (AgentCore)

Framework: Google ADK (Agent Development Kit)
Model: Gemini 3.0 Pro (native)
Runtime: AWS Bedrock AgentCore
TTS: ElevenLabs API

AWS Infrastructure

Compute: Lambda (Function URLs, API Gateway)
Storage: S3 (presigned URLs, CORS)
Auth: Cognito (JWT tokens)
CDN: CloudFront
Database: DynamoDB

Infrastructure as Code

IaC: Terraform
CI/CD: GitHub Actions

Debugging Process

Step 1: Capture the Error

Collect Information:

Error message (exact text)
Stack trace (full output)
Browser console logs
Network tab (if API-related)
Component tree (React DevTools)

Quick Commands:

# Check for TypeScript errors
pnpm typecheck

# Check build errors
pnpm build

# Run tests
pnpm test

Step 2: Categorize the Issue

React/Component Errors

Hook Rules Violation:

// ❌ Problem: Conditional hook call
function Component({ show }) {
  if (show) {
    const [state, setState] = useState() // Error!
  }
}

// ✅ Fix: Always call hooks at top level
function Component({ show }) {
  const [state, setState] = useState()
  if (!show) return null
  // ...
}

Stale Closure:

// ❌ Problem: Stale value in callback
const handleClick = () => {
  console.log(count) // Always logs initial value
}

// ✅ Fix: Use ref or dependency
const handleClick = useCallback(() => {
  console.log(count)
}, [count])

Infinite Re-render:

// ❌ Problem: Object created in render
<Component style={{ color: 'red' }} /> // New object each render

// ✅ Fix: Memoize or move outside
const style = useMemo(() => ({ color: 'red' }), [])
<Component style={style} />

TypeScript Errors

Type Mismatch:

// ❌ Problem: Missing type
const user = response.data // any type

// ✅ Fix: Add type annotation
interface User {
  id: string
  name: string
}
const user: User = response.data

Null/Undefined:

// ❌ Problem: Possible undefined
const name = user.profile.name // Error if profile undefined

// ✅ Fix: Optional chaining
const name = user?.profile?.name ?? "Unknown"

Tailwind CSS Issues

Classes Not Applying:

// ❌ Problem: Dynamic class names
const color = "red"
className={`bg-${color}-500`} // Tailwind can't detect

// ✅ Fix: Use complete class names
const bgClasses = {
  red: "bg-red-500",
  blue: "bg-blue-500"
}
className={bgClasses[color]}

Opacity Modifier Not Working:

// ❌ Problem: rgb() wrapped colors don't support /opacity
className="bg-brand-orange/50" // Won't work if brand-orange uses rgb()

// ✅ Fix: Use arbitrary value
className="bg-[#FA4616]/50"

// Or use explicit opacity
className="bg-brand-orange opacity-50"

Vite/Build Issues

HMR Not Working:

# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
pnpm dev

Import Alias Issues:

// ❌ Problem: Wrong alias
import { Button } from "components/Button" // Not configured

// ✅ Fix: Use configured alias
import { Button } from "@/components/Button" // @ = client/

TanStack Query Issues

Stale Data:

// ❌ Problem: Data not refreshing
const { data } = useQuery({
  queryKey: ["posts"],
  queryFn: fetchPosts,
})

// ✅ Fix: Invalidate after mutation
const mutation = useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ["posts"] })
  }
})

MSW Mock API Issues

Mocks Not Working:

// Check if MSW is started
// client/main.tsx should have:
if (import.meta.env.DEV) {
  const { worker } = await import('./mocks/browser')
  await worker.start()
}

Wrong Response:

// ❌ Problem: Handler not matching
http.get("/api/post", ...) // Singular

// ✅ Fix: Match exact path
http.get("/api/posts", ...) // Plural - matches request

Step 3: Backend Debugging (FastAPI/Lambda)

FastAPI Errors

Pydantic Validation Error:

# ❌ Problem: Field validation fails silently
class Request(BaseModel):
    email: str
    age: int  # Receives string "25" from JSON

# ✅ Fix: Use proper coercion or validators
class Request(BaseModel):
    email: EmailStr
    age: int = Field(..., ge=0, le=150)

    @field_validator('age', mode='before')
    def coerce_age(cls, v):
        return int(v) if isinstance(v, str) else v

CORS Issues in FastAPI:

# ❌ Problem: CORS not configured
app = FastAPI()

# ✅ Fix: Add CORS middleware (but CORS lives in terraform/main/locals.tf!)
# Check terraform/main/locals.tf for allowed_origins
# Don't duplicate CORS in FastAPI - API Gateway handles it

Lambda Cold Start:

# ❌ Problem: Slow imports at handler level
def handler(event, context):
    import heavy_library  # Slow on each cold start

# ✅ Fix: Import at module level
import heavy_library  # Loaded once

def handler(event, context):
    # Use pre-imported library

Lambda/Mangum Errors

Timeout Issues:

# Check CloudWatch logs for timeout
# Lambda timeout: 30s default, API Gateway: 29s max

# ❌ Problem: Long-running operation
def handler(event, context):
    result = slow_operation()  # Takes 60s

# ✅ Fix: Use async or step functions for long operations
# Or increase Lambda timeout in terraform/main/lambda.tf

Environment Variables Not Found:

# Check SSM parameter store
aws ssm get-parameter --name "/faiston-nexo/google-api-key"

# In Lambda, use:
import os
api_key = os.environ.get("GOOGLE_API_KEY", "")

Step 4: Agent Debugging (Google ADK/AgentCore)

Google ADK Errors

Agent Not Responding:

# ❌ Problem: Agent returns empty response
async for event in runner.run_async(...):
    if event.is_final_response():
        return event.content.parts[0].text  # May be None

# ✅ Fix: Handle empty responses
async for event in runner.run_async(...):
    if event.is_final_response():
        if event.content and event.content.parts:
            return event.content.parts[0].text
return "Desculpe, não consegui processar sua solicitação."

Session Service Issues:

# ❌ Problem: Session not persisting
session_service = InMemorySessionService()
# Creates new session each Lambda invocation

# ✅ Fix: Use AgentCore Memory for persistence
# Or pass session_id from frontend consistently

Model API Errors:

# Check GOOGLE_API_KEY is set
# Gemini model: "gemini-3-pro-preview"

# Common errors:
# - 429: Rate limit exceeded
# - 400: Invalid prompt/content
# - 401: Invalid API key

AgentCore Runtime Errors

JWT Authorization Failed:

Error: AgentCore access denied. Check JWT authorizer configuration.

# Verify Cognito config in .bedrock_agentcore.yaml:
authorizerConfiguration:
  customJWTAuthorizer:
    discoveryUrl: https://cognito-idp.us-east-2.amazonaws.com/us-east-2_6Vzhr0J6M/.well-known/openid-configuration
    allowedClients: [dqqebean5q4fq14bkp2bofnsj]

Session ID Too Short:

// ❌ Problem: Session ID < 33 characters
const sessionId = "my-session";  // 10 chars - FAILS

// ✅ Fix: Generate proper session ID
function generateSessionId(): string {
  return `session-${crypto.randomUUID().replace(/-/g, '')}`;
  // Result: 41 characters
}

Endpoint DEFAULT Not Ready:

Error: Endpoint DEFAULT is not ready

# Wait for deployment to complete
# Check GitHub Actions workflow status
# Verify with: agentcore status --agent faiston_nexo_agents

Step 5: AWS Debugging

S3 Presigned URL Issues

CORS 307 Redirect (CRITICAL):

# ❌ Problem: S3 returns 307 redirect, browser blocks due to CORS
presigned_url = s3_client.generate_presigned_url(...)
# URL uses global endpoint, redirects to regional

# ✅ Fix: Use regional endpoint with s3v4 signature
from botocore.config import Config

s3_client = boto3.client(
    's3',
    region_name='us-east-2',
    config=Config(
        signature_version='s3v4',
        s3={'addressing_style': 'virtual'}
    )
)

Presigned URL Expired:

# Default expiration: 3600 seconds (1 hour)
# Check ExpiresIn parameter
presigned_url = s3_client.generate_presigned_url(
    'get_object',
    Params={'Bucket': bucket, 'Key': key},
    ExpiresIn=7200  # 2 hours
)

Cognito Errors

Token Expired:

// Check token expiration in cognito.ts
const fiveMinutes = 5 * 60 * 1000;
if (Date.now() > tokens.expiresAt - fiveMinutes) {
  tokens = await refreshCognitoTokens();
}

User Not Found:

# Create user in Cognito console
# Or use AWS CLI:
aws cognito-idp admin-create-user \
  --user-pool-id us-east-2_6Vzhr0J6M \
  --username admin@faiston.com

CloudFront Issues

Cache Not Invalidating:

# Create invalidation
aws cloudfront create-invalidation \
  --distribution-id E1234567890 \
  --paths "/*"

403 Forbidden:

# Check Origin Access Control (OAC) configuration
# Verify S3 bucket policy allows CloudFront

Step 6: Terraform Debugging

State Issues

State Lock Error:

# ❌ Problem: State is locked
Error: Error locking state: Error acquiring the state lock

# ✅ Fix: Force unlock (use with caution!)
terraform force-unlock LOCK_ID

# Or wait for other process to complete

State Drift:

# Detect drift
terraform plan

# If manual changes were made:
terraform refresh  # Update state from actual
# Or
terraform import aws_s3_bucket.example bucket-name

Plan Errors

Resource Already Exists:

# ❌ Problem: Trying to create existing resource
Error: A bucket with this name already exists

# ✅ Fix: Import existing resource
terraform import aws_s3_bucket.frontend faiston-nexo-frontend-prod

# Or delete resource if not needed
aws s3 rb s3://bucket-name --force

Invalid Provider Configuration:

# Check terraform/main/providers.tf
provider "aws" {
  region = "us-east-2"
}

# Verify credentials
aws sts get-caller-identity

GitHub Actions Deployment

Terraform Apply Failed:

# Check workflow logs in GitHub Actions
# Common issues:
# - Missing secrets (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# - State bucket permissions
# - Resource conflicts

# Never deploy from local console!
# Always use: .github/workflows/terraform-*.yml

Debugging Checklist

Before declaring a bug fixed:

Error no longer appears in console
TypeScript compiles without errors
Build succeeds (pnpm build)
Tests pass (pnpm test)
Works on mobile viewport
Works with slow network (DevTools throttle)
No memory leaks (long usage)

Common Quick Fixes

# Reset everything
rm -rf node_modules && pnpm install

# Clear Vite cache
rm -rf node_modules/.vite

# TypeScript issues
pnpm typecheck

# Check for unused exports
pnpm build 2>&1 | grep -i "unused"

Response Format

When debugging:

Acknowledge the issue
- "I see the error: [exact message]"
- "Let me investigate systematically"
Gather information
- Check console logs
- Read relevant code
- Test reproduction steps
Identify root cause
- "The issue is caused by [explanation]"
- "This happens because [technical reason]"
Provide the fix
- Show exact code changes
- Explain why this fixes it
Verify the fix
- Run typecheck
- Test in browser
- Check edge cases

Remember: Most React bugs are about timing, state, or missing dependencies!

bug-detective

SKILL.md