@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/troubleshooting.en.md

@@ -0,0 +1,637 @@
+# Troubleshooting
+
+Consolidated FAQ and problem-solving guide for `development-utility-kit`. Covers skills, agents, hooks, Honcho, stacks (backend, frontend, mobile, fullstack), adopting existing projects, the senior+ gate, and Git Flow.
+
+> **Principle**: try the specialist agent for the area first. Only escalate to a human in the 4 Product Owner situations or 3 Tech Lead situations described at the end of this document.
+
+Each item follows the pattern:
+
+- **Symptom** — what you see.
+- **Cause** — why it happens.
+- **Solution** — command or step-by-step.
+
+## Skills
+
+### Skill does not trigger on a trigger phrase
+
+- **Symptom**: you write "audit coverage" but `test-coverage-auditor` does not run.
+- **Cause**: the skill's frontmatter `description` does not exactly match the phrase you used. Matching is keyword-based on the frontmatter.
+- **Solution**: open `.claude/skills/<skill>/SKILL.md`, read the `description`, adjust your phrase, or edit the description to include the synonym:
+  ```bash
+  cat .claude/skills/test-coverage-auditor/SKILL.md | head -20
+  ```
+  Restart the session after editing the frontmatter.
+
+### Specific skill overridden by `project-manager`
+
+- **Symptom**: when asking "review code", `project-manager` (catch-all) answers instead of the more specific skill.
+- **Cause**: no specific skill matched the exact phrase; the catch-all takes over.
+- **Solution**: prefer the canonical phrase from the skill (see the "Skills" table in `CLAUDE.md`). E.g., for PR review use "review the PR" or "audit this change". A more specific skill always wins on match.
+
+### `caveman` cutting too much substance
+
+- **Symptom**: responses become so telegraphic they omit necessary context.
+- **Cause**: caveman is in ULTRA mode (default for code).
+- **Solution**: downgrade explicitly:
+  ```
+  caveman lite
+  ```
+  or turn it off entirely:
+  ```
+  stop caveman
+  ```
+  Re-enable when you want: `caveman full`.
+
+### `honcho-memory` skill does not inject `[HONCHO MEMORY]` block
+
+- **Symptom**: you saved memories but the block does not appear at the start of responses.
+- **Cause**: the `UserPromptSubmit` hook that injects the block is not configured in `.claude/settings.json`.
+- **Solution**: run `/honcho setup` or manually edit `settings.json` (see Honcho section below).
+
+## Agents
+
+### Agent `analyst` returns "Discovery artifact missing"
+
+- **Symptom**: when asking "break into PLAN", `analyst` refuses with a message about a discovery artifact.
+- **Cause**: ADR-013/ADR-017 require `docs/discovery/DISCOVERY_*.md` produced by `grill-me` before `analyst` can be invoked by a human.
+- **Solution**:
+  ```
+  grill-me
+  ```
+  Answer the interview; `grill-me` generates `DISCOVERY_*.md` and hands off to `analyst` automatically. Autonomous callers (`sprint-runner`, `release-engineer`) are exempt.
+
+### `sprint-runner` stopped mid-checkpoint
+
+- **Symptom**: the agent stopped after Sprint X and did not resume Sprint X+1.
+- **Cause**: intermittent error or session token limit.
+- **Solution**: continue manually:
+  ```
+  run sprint X+1
+  ```
+  If it persists, read the latest `PLAN_*.md` to understand where it stopped and open a ticket.
+
+### `tech-lead` does not approve merge
+
+- **Symptom**: PR stays in "changes requested" without approval.
+- **Cause**: senior+ gate failed OR a convention is violated (separate Angular files, commit with AI reference, etc.).
+- **Solution**: read the `tech-lead`'s diagnosis in the PR comment. Send back to the indicated developer (`backend-developer`, `frontend-developer`) with the requested fix. Do not manually approve.
+
+### Agent chosen by `project-manager` seems wrong
+
+- **Symptom**: you asked "design DB" and it triggered `backend-developer` instead of `database-engineer`.
+- **Cause**: ambiguous keyword.
+- **Solution**: be explicit: "use database-engineer to design schema for X". `project-manager` accepts override.
+
+### Agent escalates directly to human unnecessarily
+
+- **Symptom**: specialist asks "what's your preference?" instead of deciding.
+- **Cause**: violation of the Autonomy Matrix.
+- **Solution**: reply "you decide" and cite the rule. If it persists, open a ticket — it may be drift in the agent prompt.
+
+## Hooks (Claude Code)
+
+> These are Claude Code hooks (`PostToolUse`, `UserPromptSubmit`, etc.), different from git hooks (see [Git Flow](git-flow)).
+
+### Hook blocks every write
+
+- **Symptom**: every `Write` call returns a hook error.
+- **Cause**: `pre-push-guard.sh` or another script exited with exit != 0; or the script path in `settings.json` is invalid.
+- **Solution**: read hook stderr in the log. Check the script's exit code. Edit `.claude/settings.json` and temporarily disable:
+  ```json
+  "hooks": {
+    "PostToolUse": []
+  }
+  ```
+
+### Hook script not found
+
+- **Symptom**: `python3: can't open file '.../scripts/check-sql-files.py'` or similar.
+- **Cause**: `settings.json` references up to 5 scripts in `scripts/hooks/` that were not created yet in the project.
+- **Solution**: create the script with a stub that returns 0:
+  ```python
+  #!/usr/bin/env python3
+  # stub hook — replace with real validation later
+  import sys
+  sys.exit(0)
+  ```
+  Or remove the entry from `settings.json` if the hook is not needed in this project.
+
+### `${CLAUDE_PLUGIN_ROOT}` not resolved
+
+- **Symptom**: the path appears literal in logs (with `${CLAUDE_PLUGIN_ROOT}` instead of expanded value).
+- **Cause**: the plugin's environment variable is not available on the machine/session.
+- **Solution**: two options:
+  1. Export the variable before starting Claude:
+     ```bash
+     export CLAUDE_PLUGIN_ROOT=/path/to/development-utility-kit
+     ```
+  2. Remove the hook from `settings.json` if it is not required locally.
+
+### Prettier fails in `PostToolUse`
+
+- **Symptom**: format hook fails with `prettier: command not found`.
+- **Cause**: `node_modules/.bin/prettier` does not exist.
+- **Solution**:
+  ```bash
+  npm install --save-dev prettier
+  npx prettier --version  # confirm installation
+  ```
+
+### Hook runs in an infinite loop
+
+- **Symptom**: PostToolUse hook re-triggers when it edits the same file it observes.
+- **Cause**: the hook writes to the same path it watches.
+- **Solution**: add a `matcher` filter in `settings.json` to exclude the tool type, or use timestamp/flag guarding.
+
+## Honcho memory
+
+### `/honcho status` returns FAIL
+
+- **Symptom**: Honcho status shows connection error.
+- **Cause**: `~/.honcho/config.json` missing, malformed, or Honcho server offline at the configured endpoint.
+- **Solution**: check the config:
+  ```bash
+  cat ~/.honcho/config.json
+  ```
+  Test the endpoint manually:
+  ```bash
+  curl https://honcho.<your-host>/v3/health
+  ```
+  Reconfigure with `/honcho setup` if needed.
+
+### `[HONCHO MEMORY]` block does not appear in prompt
+
+- **Symptom**: saved memories exist but are not injected.
+- **Cause**: `UserPromptSubmit` hook that injects them is missing from `.claude/settings.json`.
+- **Solution**: run `/honcho setup` to reconfigure, or add manually:
+  ```json
+  "hooks": {
+    "UserPromptSubmit": [
+      {"command": "node .claude/skills/honcho-memory/inject.js"}
+    ]
+  }
+  ```
+
+### Old memories reappear even after `/honcho forget`
+
+- **Symptom**: deleted memory keeps being surfaced.
+- **Cause**: Honcho inference re-creates the memory from recent prompts (`inferenceEnabled: true`).
+- **Solution**: disable inference in `~/.honcho/config.json`:
+  ```json
+  { "inferenceEnabled": false }
+  ```
+  Or accept that inferred memories may come back and use `/honcho forget` repeatedly for rare patterns.
+
+### Forgot dry-run mode
+
+- **Symptom**: local tests saved real memories to the server.
+- **Cause**: `HONCHO_DRY_RUN=1` was not set.
+- **Solution**: for future tests, export:
+  ```bash
+  export HONCHO_DRY_RUN=1
+  ```
+  To clean server garbage: `/honcho list` -> identify test entries -> `/honcho forget`.
+
+### `/honcho save` does not persist across sessions
+
+- **Symptom**: you saved in session A, opened session B, and the memory is gone.
+- **Cause**: different `peerId` between sessions (different machine, different profile).
+- **Solution**: confirm `peerId` in `~/.honcho/config.json`. Keep the same one across all machines used by the same dev.
+
+## Backend (Java 25 + Spring Boot 4)
+
+### Port 8080 in use
+
+- **Symptom**: `Web server failed to start. Port 8080 was already in use.`
+- **Cause**: another process (another app, container) occupies the port.
+- **Solution**:
+  ```bash
+  # Linux/Mac
+  lsof -i :8080 | grep LISTEN
+  # Windows (PowerShell)
+  netstat -ano | findstr :8080
+  taskkill /PID <pid> /F
+  ```
+  Or change `server.port` in `application.yml`.
+
+### Wrong JDK (different version than required)
+
+- **Symptom**: compile errors like `record` not recognized, or `release version X not supported`.
+- **Cause**: active JDK is < 25.
+- **Solution** (sdkman):
+  ```bash
+  sdk list java | grep 25
+  sdk install java 25.0.1-tem
+  sdk use java 25.0.1-tem
+  java -version   # must show 25
+  ```
+
+### Flyway lock stuck
+
+- **Symptom**: migrations do not run and the log shows `unable to acquire lock`.
+- **Cause**: a previous process died without releasing the lock in `flyway_schema_history`.
+- **Solution**:
+  ```bash
+  ./mvnw flyway:repair
+  ```
+  Or via SQL:
+  ```sql
+  DELETE FROM flyway_schema_history WHERE success = false;
+  ```
+
+### CORS blocking in production
+
+- **Symptom**: frontend receives missing `Access-Control-Allow-Origin`.
+- **Cause**: `SecurityFilterChain` with `*` in dev but restricted in prod, or missing CORS config.
+- **Solution**: never use `*` in prod. Configure explicit domains:
+  ```java
+  config.setAllowedOrigins(List.of("https://app.company.com"));
+  ```
+
+### Secret in code
+
+- **Symptom**: `security-engineer` or `gate-keeper` blocks PR with credential detected message.
+- **Cause**: password, token, or key hardcoded in `.java`, `.yml`, `.properties`.
+- **Solution**: move to env var or Vault. Rewrite history if the secret was already committed:
+  ```bash
+  git filter-repo --invert-paths --path <file>
+  ```
+  And revoke the secret at the provider immediately.
+
+### Testcontainers do not start in CI
+
+- **Symptom**: `Could not find a valid Docker environment` in GitHub Actions.
+- **Cause**: runner without Docker in daemon mode.
+- **Solution**: use `ubuntu-latest` (has Docker), or run `docker info` in a step before `mvn verify`.
+
+## Frontend (Angular 21)
+
+### HMR not refreshing
+
+- **Symptom**: saving file does not reload the browser.
+- **Cause**: filesystem watch does not trigger (WSL, Docker volume, polling required).
+- **Solution**:
+  ```bash
+  npm start -- --poll=500
+  ```
+
+### Signal does not dispatch — `OnPush` stale
+
+- **Symptom**: state changed but component does not re-render.
+- **Cause**: you mutated the array instead of creating a new reference (`signal().push(item)`).
+- **Solution**:
+  ```ts
+  // Wrong
+  this.items().push(newItem);
+  // Right
+  this.items.update(arr => [...arr, newItem]);
+  // Or
+  this.items.set([...this.items(), newItem]);
+  ```
+
+### `ChangeDetectorRef.markForCheck()` abuse
+
+- **Symptom**: you need to call `cdr.markForCheck()` everywhere.
+- **Cause**: Signals are not being used — you are still in old zone.js pattern.
+- **Solution**: refactor state management to use Signals consistently. They propagate changes automatically in `OnPush`.
+
+### Bundle > 500KB
+
+- **Symptom**: build warning about exceeded bundle budget.
+- **Cause**: heavy imports, large dependencies, no lazy loading.
+- **Solution**:
+  ```bash
+  npm run build -- --stats-json
+  npx webpack-bundle-analyzer dist/browser/stats.json
+  ```
+  Identify heavy imports, fragment into lazy routes, remove unused dependencies.
+
+### E2E timeout (Playwright)
+
+- **Symptom**: `Test timeout of 30000ms exceeded`.
+- **Cause**: browser not installed, app slow to start, wrong selector.
+- **Solution**:
+  ```bash
+  npx playwright install --with-deps
+  ```
+  Increase the timeout in `playwright.config.ts` only if the app is legitimately slow:
+  ```ts
+  timeout: 60_000
+  ```
+
+### `templateUrl` pointing to missing file
+
+- **Symptom**: build breaks with `ENOENT: no such file 'name.html'`.
+- **Cause**: someone tried inline template and broke it. Reminder: three separate files are **mandatory**.
+- **Solution**: create `name.html` and `name.scss` next to `name.ts`, and use:
+  ```ts
+  @Component({
+    templateUrl: './name.html',
+    styleUrl: './name.scss'
+  })
+  ```
+
+## Mobile (React Native + Expo)
+
+### `pod install` fails (iOS)
+
+- **Symptom**: pod version or checksum errors.
+- **Solution**:
+  ```bash
+  cd ios && pod install --repo-update
+  # If it persists:
+  rm -rf ios/Pods ios/Podfile.lock
+  cd ios && pod install
+  ```
+
+### Gradle daemon stuck (Android)
+
+- **Symptom**: build hangs at `Daemon will be stopped`.
+- **Solution**:
+  ```bash
+  cd android && ./gradlew --stop
+  ./gradlew clean
+  npx expo run:android
+  ```
+
+### Metro cache corrupted
+
+- **Symptom**: app starts with `Cannot find module` error.
+- **Solution**:
+  ```bash
+  npx expo start --clear
+  # Or force full cleanup:
+  watchman watch-del-all
+  rm -rf $TMPDIR/metro-*
+  npx expo start --clear
+  ```
+
+### `AsyncStorage` deprecated
+
+- **Symptom**: warning about core AsyncStorage.
+- **Cause**: native package removed in RN 0.73+.
+- **Solution**:
+  ```bash
+  npm install @react-native-async-storage/async-storage
+  ```
+  And adjust imports.
+
+### Library incompatible with New Architecture
+
+- **Symptom**: app crashes at runtime with TurboModule error.
+- **Cause**: lib still uses legacy bridge.
+- **Solution**: check compatibility on `reactnative.directory` (filter "New Architecture"). Use `npx react-native-community-upgrade-helper` for breaking changes in your version.
+
+## Fullstack
+
+### CORS blocking Angular -> Spring
+
+- **Symptom**: missing `Access-Control-Allow-Origin` in front-end calls.
+- **Cause**: `CorsConfig` in the backend does not include `http://localhost:4200`.
+- **Solution**: add to `WebMvcConfigurer` or `SecurityFilterChain`:
+  ```java
+  config.setAllowedOrigins(List.of("http://localhost:4200"));
+  config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","PATCH"));
+  config.setAllowCredentials(true);
+  ```
+
+### TS types out of sync with backend
+
+- **Symptom**: frontend interface differs from real payload.
+- **Cause**: backend contract changed but types were not regenerated.
+- **Solution**:
+  ```bash
+  npx openapi-typescript http://localhost:8080/v3/api-docs -o src/types/api.d.ts
+  ```
+  Add this step to CI so it fails when the contract changes without type updates.
+
+### Docker compose network — frontend cannot reach backend
+
+- **Symptom**: frontend returns `ECONNREFUSED` or `getaddrinfo ENOTFOUND backend`.
+- **Cause**: frontend uses `localhost` instead of the Docker service name.
+- **Solution**: inside the Docker network, use the service name:
+  ```yaml
+  environment:
+    API_URL: http://backend:8080
+  ```
+  In the dev's browser, use `http://localhost:8080` (exposed port).
+
+### Backend starts after frontend
+
+- **Symptom**: frontend loads before backend is ready and breaks.
+- **Cause**: `depends_on` without a healthcheck condition.
+- **Solution**: add `HEALTHCHECK` in the backend Dockerfile and use `condition: service_healthy`:
+  ```yaml
+  depends_on:
+    backend:
+      condition: service_healthy
+  ```
+
+### Port 4200 already in use
+
+- **Solution**:
+  ```bash
+  npm start -- --port 4201
+  ```
+
+## Adopting an existing project
+
+### `update-template` destroyed custom rules
+
+- **Symptom**: your `CLAUDE.md` was reset to default, losing the `Project Identity` section.
+- **Cause**: merge failed to preserve the custom section.
+- **Solution**: restore from backup:
+  ```bash
+  ls CLAUDE.md.bak.*
+  cp CLAUDE.md.bak.2026-05-26 CLAUDE.md
+  ```
+  Reapply customization manually by comparing with the new template.
+
+### Vault without `.obsidian/`
+
+- **Symptom**: `brain-keeper` does not write into `docs/brain/`.
+- **Cause**: Obsidian vault structure was not created.
+- **Solution**:
+  ```bash
+  mkdir -p docs/brain/.obsidian
+  ```
+  Run `brain-keeper` again.
+
+### Agents with wrong path
+
+- **Symptom**: agent references missing file in `.claude/agents/`.
+- **Cause**: `active-project` failed partially.
+- **Solution**:
+  ```bash
+  duk active-project <path> --force
+  ```
+
+### `settings.json` merge conflicts
+
+- **Symptom**: duplicated or missing hooks after `update-template`.
+- **Cause**: file is not automatically merged — it overwrites.
+- **Solution**: manually compare with `.claude/settings.json.bak.*` and preserve local rules.
+
+### Missing Honcho config
+
+- **Symptom**: `/honcho` returns "skill not found".
+- **Solution**:
+  ```bash
+  ls .claude/skills/honcho-memory/
+  # Must contain: config.json, SKILL.md, honcho.js
+  ```
+  If missing, run `duk update-template` to restore.
+
+## Senior+ gate / quality
+
+### Coverage < 85%
+
+- **Symptom**: `gate-keeper` failed with "Backend coverage (lines) 78% < 85%".
+- **Cause**: new files without tests, or uncovered paths.
+- **Solution**: call `qa-engineer` or let `gate-keeper` generate missing tests automatically. Per-file coverage:
+  ```bash
+  ./mvnw jacoco:report
+  open target/site/jacoco/index.html
+  ```
+
+### Mutation score < 70%
+
+- **Symptom**: PIT failed with mutation < 70% in `domain/` or `application/`.
+- **Cause**: tests exist but do not kill mutations — usually weak asserts.
+- **Solution**:
+  ```bash
+  ./mvnw verify -Ppitest
+  open target/pit-reports/index.html
+  ```
+  Strengthen asserts (use `assertThat(...).isEqualTo(...)` instead of `assertNotNull`).
+
+### Lighthouse < 0.80
+
+- **Symptom**: gate fails on performance.
+- **Cause**: LCP, CLS, or TBT above threshold.
+- **Solution**: analyze each metric:
+  - LCP > 2500ms: heavy hero image, custom font without `font-display: swap`.
+  - CLS > 0.1: images without `width/height` causing layout shift.
+  - TBT > 300ms: large JS bundle, insufficient lazy loading.
+
+### A11y violations serious/critical
+
+- **Symptom**: jest-axe or playwright-axe failed.
+- **Cause**: insufficient contrast, missing label, broken tab order.
+- **Solution**: read the axe report. Each violation has a link to WCAG. Fix in the component — `ux-designer` can help.
+
+### SpotBugs CRITICAL
+
+- **Symptom**: build fails with critical SpotBugs bug.
+- **Solution**:
+  ```bash
+  ./mvnw spotbugs:gui
+  ```
+  Investigate every CRITICAL/HIGH. Do not ignore — fix or justify in `@SuppressFBWarnings` with a clear reason.
+
+### `npm audit` HIGH/CRITICAL
+
+- **Symptom**: gate fails on dependency vulnerability.
+- **Solution**:
+  ```bash
+  npm audit fix
+  # For vulns requiring breaking change:
+  npm audit fix --force  # caution, may bump major
+  ```
+
+## Git Flow / commits
+
+### Commit with "Claude" / "Anthropic" / "AI" in the body
+
+- **Symptom**: `tech-lead` blocked the PR for commit restriction.
+- **Cause**: violation of the non-negotiable rule documented in [Git Flow](git-flow).
+- **Solution**: rewrite history:
+  ```bash
+  # Latest commit:
+  git commit --amend
+  # Several commits:
+  git rebase -i HEAD~N
+  # Mark each as `reword`, save, edit the message.
+  ```
+  If already pushed on your own branch:
+  ```bash
+  git push --force-with-lease origin feature/<your-branch>
+  ```
+
+### PR rejected by `tech-lead`
+
+- **Symptom**: review with "changes requested".
+- **Cause**: senior+ gate failed, convention violated, or the separate-Angular-files rule broken.
+- **Solution**: read the `tech-lead`'s inline diagnosis on the PR. Send back to the indicated developer with the fix. Do not force the merge.
+
+### Wrong target branch for PR
+
+- **Symptom**: you opened a PR from `feature/x` directly to `main`.
+- **Cause**: confusion about the correct target.
+- **Solution**: close the PR, recreate it:
+  ```bash
+  gh pr create --base develop --head feature/x
+  ```
+  Remember: `feature/*` -> `develop`, `hotfix/*` -> `main` + `develop`.
+
+### Forgot hotfix back-merge into `develop`
+
+- **Symptom**: same bug regresses in the next release.
+- **Cause**: hotfix landed in `main` but not in `develop`.
+- **Solution**:
+  ```bash
+  git checkout develop
+  git cherry-pick <fix-SHA-from-main>
+  git push origin develop
+  ```
+
+### Accidental force push on shared branch
+
+- **Symptom**: other devs complain that pull fails.
+- **Cause**: you did `git push --force` on `main`/`develop`/`release/*`.
+- **Solution**: WHILE STILL FRESH — ask another dev with the full local history to do:
+  ```bash
+  git push --force-with-lease origin <branch>
+  ```
+  to restore. Rewriting shared history is an incident — notify `tech-lead`.
+
+### Commit outside Conventional Commits
+
+- **Symptom**: `commit-msg` hook rejected it or `tech-lead` complained in review.
+- **Solution**: `git commit --amend` and use the `<type>(<scope>): <description>` format. See types in [Git Flow](git-flow).
+
+## When to open a ticket / ask for human help
+
+Specialists **DO NOT** escalate to a human directly. Only PO or TL escalate, and only in the following situations:
+
+### Product Owner escalates ONLY in 4 situations
+
+1. Irreversible action on real customer data (delete/overwrite without backup).
+2. Relevant financial cost (paid SaaS, tier change).
+3. Breaking change on PUBLIC contract already published (external client).
+4. Identity/brand change approved by another area.
+
+### Tech Lead escalates ONLY in 3 situations
+
+1. Technical requirement conflict that cannot be resolved by grounding.
+2. Breaking change on public production contract (window with external client).
+3. Infra cost > R$ 200/month additional.
+
+### Escalation format
+
+Never an open question. Always **proposal + recommendation + impact of the opposite decision**:
+
+> "Provision managed Redis Cluster (+R$ 380/month) to support 10x traffic in 6 months. I recommend approving now; if we keep single-node, cache queue in 2 months."
+
+See [Autonomy matrix](autonomy-matrix) for full details.
+
+## Cross-references
+
+- [Agents reference](agents-reference) — when to call each agent.
+- [Skills reference](skills-reference) — triggers and responsibilities of each skill.
+- [Hooks reference](hooks-reference) — Claude Code hooks (do not confuse with git hooks).
+- [Honcho memory](honcho-memory) — persistent cross-session memory.
+- [Git Flow](git-flow) — branch, commit, and PR flow.
+- [Quality gate](quality-gate) — thresholds and tools.
+- [Autonomy matrix](autonomy-matrix) — who decides what.
+- [Pipeline](pipeline) — standard task pipeline.