saravanakumardb
32c7b1ba7e
- roadmap-execution: phased roadmap execution with checkpoints - new-product-scaffold: scaffold new ByteLyst product repos - prd-to-implementation: convert PRDs to concrete plans - cross-repo-debug: systematic multi-repo debugging - backend-module-crud: Fastify CRUD modules (types/repo/routes/tests) - platform-integration: wire products into common platform - refactor-with-tests: test-first safe refactoring - test-gap-analysis: coverage gap identification and remediation - type-safety-sweep: TypeScript error triage and fix - dependency-health-check: cross-repo dependency audit - pre-release-validation: comprehensive release checklist - docker-production-prep: production Docker images - agents-md-sync: keep AI instruction files accurate - ecosystem-audit: full ecosystem health dashboard
146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
---
|
|
name: cross-repo-debug
|
|
description: 'Systematically debug issues that span multiple ByteLyst repos, tracing from symptom to root cause across service boundaries.'
|
|
argument-hint: 'Symptom description, e.g. "auth token rejected by FlowMonk backend", "design tokens not applied in PeakPulse iOS", "platform-service 500 on /api/flags"'
|
|
agent: 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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
cd learning_ai_common_plat && pnpm build
|
|
```
|
|
- Reinstall in consumer repos if package API changed:
|
|
```bash
|
|
cd <product> && pnpm install
|
|
```
|
|
|
|
### Step 5: Validate Across Repos
|
|
|
|
After fixing:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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>
|
|
```
|