learning_ai_common_plat/AI.dev/PROMPTS/cross-repo-debug.md

name	description	argument-hint	agent
cross-repo-debug	Systematically debug issues that span multiple ByteLyst repos, tracing from symptom to root cause across service boundaries.	Symptom description, e.g. "auth token rejected by FlowMonk backend", "design tokens not applied in PeakPulse iOS", "platform-service 500 on /api/flags"	agent

Cross-Repo Debug Prompt

Systematically diagnose and fix bugs that span multiple repositories in the ByteLyst ecosystem.

Context — ByteLyst Architecture

Service topology:

Product clients (web/mobile)
    → Product backend (Fastify, port 40xx)
        → @bytelyst/* packages (shared libraries)
        → platform-service (port 4003: auth, flags, billing, etc.)
            → Cosmos DB (productId multi-tenancy)
            → Azurite (blob storage)

Common cross-repo failure points:

1. Auth chain: platform-service issues JWT → product backend validates → client stores
2. Package version mismatch: Zod, jose, or @azure/cosmos version conflicts between packages and services
3. Config drift: .env vars, .npmrc, or product.json out of sync
4. API contract breaks: platform-service endpoint changed but consumer not updated
5. Design token gaps: token JSON updated but generated files not regenerated/copied

Debug Protocol

Step 1: Symptom Capture

Document:

• What: Exact error message, HTTP status, or unexpected behavior
• Where: Which repo/service/file/line
• When: Always, intermittent, or after a specific change
• Who: Which product(s) affected

Step 2: Trace the Call Chain

Starting from the symptom, trace backwards:

1. Client (web/mobile) — check network tab, API client code
2. Product backend — check routes.ts, request-context.ts, auth.ts
3. Shared packages — check @bytelyst/* import versions
4. Platform service — check the module handling this request
5. Data layer — check Cosmos queries, partition keys, productId

For each layer, check:

• Is the service running? (curl http://localhost:<port>/health)
• Are env vars set? (compare with .env.example)
• Are packages built? (pnpm build in common_plat)
• Are types aligned? (pnpm typecheck)

Step 3: Isolate

Run targeted tests to narrow scope:

# Test the specific module
pnpm --filter @lysnrai/platform-service test -- --grep "auth"
pnpm --filter @bytelyst/auth test

# Test the product backend
cd <product>/backend && pnpm test

# Typecheck across repos
cd learning_ai_common_plat && pnpm typecheck
cd <product> && pnpm typecheck

Step 4: Fix

• Fix in the lowest-level repo first (packages → services → products)
• Rebuild packages if you changed a @bytelyst/* package:

  cd learning_ai_common_plat && pnpm build
  

• Reinstall in consumer repos if package API changed:

  cd <product> && pnpm install
  

Step 5: Validate Across Repos

After fixing:

# 1. Rebuild common platform
cd learning_ai_common_plat && pnpm build && pnpm test

# 2. Reinstall + test affected products
cd <product> && pnpm install && pnpm test

# 3. Verify health endpoints
curl -s http://localhost:4003/health | jq .
curl -s http://localhost:<product-port>/health | jq .

Step 6: Commit in Correct Repos

Commit in dependency order:

# Fix in common_plat first
cd learning_ai_common_plat
git add . && git commit -m "fix(<package>): <description>" && git push

# Then fix in product repo
cd <product>
git add . && git commit -m "fix(<scope>): <description>" && git push

Common Diagnosis Patterns

"Module not found" or import errors

• Check: Was pnpm build run in common_plat?
• Check: Are file: refs in product's package.json pointing to correct paths?
• Check: Is the export in the package's src/index.ts?

"Zod validation failed" or schema errors

• Check: Service uses self-contained Zod schemas in src/lib/config.ts (not from @bytelyst/config)
• Check: Zod version alignment between package and service

"401 Unauthorized" across services

• Check: JWT_SECRET matches between platform-service and product backend
• Check: Token is being forwarded in Authorization: Bearer header
• Check: Product backend's auth.ts re-exports correctly from @bytelyst/auth

Design tokens not working

• Check: Token generator was run (pnpm --filter @bytelyst/design-tokens generate)
• Check: Generated files were copied to consumer repos
• Check: CSS custom properties use correct product prefix (--er-, --fm-, --di-*, etc.)

Output

For each issue found, report:

### Issue: <title>
- **Root cause:** <repo>/<file> — <explanation>
- **Fix:** <what was changed>
- **Commit:** `<hash>` in `<repo>`
- **Validated:** <test commands run>