# Kuan Yin — Troubleshooting

> Technical doc 32.16.1.10.

## Build & test

| Symptom                                                | Cause / fix                                                                                                                               |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `NX Failed to parse pnpm lockfile … reading 'forEach'` | A stray `pnpm install` rewrote the lockfile. `git checkout -- pnpm-lock.yaml`; do not re-run install.                                     |
| Nx reports duplicate projects                          | Worktrees expose duplicate project names. Bypass Nx: `npx tsc --noEmit` and `npx vitest run` from the lib dir.                            |
| Cross-lib test import fails to resolve `@kuanyin/*`    | The test lib's `vitest.config.ts` needs `resolve.alias` mapping each `@kuanyin/*` to `../<lib>/src/index.ts` (see `@kuanyin/evaluation`). |
| Pre-commit "stub-indicator" hit on a benign comment    | Reword to avoid the token, or annotate `// stub:legitimate <reason>` / `// random:legitimate <reason>` on the same line.                  |

## Runtime

| Symptom                                                       | Cause / fix                                                                                                                 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Auth returns `authenticated: false`                           | Credential keys are camelCase (`clientId`, `codeVerifier`, …); MFA requires an `mfaToken` in credentials.                   |
| Trust composite is unexpectedly low / `reliabilityLabel: new` | Trust factor scores are on a **0–100** scale, not 0–1.                                                                      |
| `predictCascadeRisk` returns 0                                | `currentHealthScore` must be **0–1**; `assessCommunityHealth().overallScore` is 0–100 — divide by 100.                      |
| Rate limiter never throttles                                  | The token bucket refills by elapsed time; with `currentTokens > 0` or a stale `lastRefillTimestamp`, requests are admitted. |
| Cache reads miss right after write                            | TTL elapsed (`setWithTTL`) or the key was invalidated by tag/prefix. Check `getStats()`.                                    |
| Irreversible action silently not applied                      | Working as intended: `requireHumanReviewForBan` gates bans/terminations for human review.                                   |

## Analysis quality

- **Harm score seems low for an obviously hostile message** — keyword matches
  drive the base score; caps/exclamation add boosts. A message with no seeded
  keywords still scores via boosts but lower. Tune via the harm-keyword seeds /
  community config rather than hard-coding.
- **Sarcasm/coded language slips through** — enable `detectSarcasm` and
  `detectCodedLanguage` in the precognition pipeline and the `advanced-nlp`
  dog-whistle/obfuscation detectors; single-message classifiers miss context, so
  add the `threat-detection` contextual conversation analysis.

## Escalation

If a problem affects safety (a crisis not routed, a shield not raised, a minor
exposed), treat it as a P1 and follow `15-incident-response.md` — do not wait on
a normal fix cycle.
