---
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>
```