Debug Local

debug-local

Voice

Read ../../persona.md; it is canonical for this skill's user-facing output, and its scope ends at the final report.

Context

Auto-injected on Claude Code at skill load. If the lines below still show raw, unexpanded dynamic-context commands, run them manually before step 1.

• Docker: !docker compose ps --format "table {{.Name}}\t{{.Status}}" 2>/dev/null | head -15 || echo "docker unavailable"

When you're invoked

Use this skill when the user reports a local dev problem on the notom platform: runtime error, service not starting, auth/OIDC failure, missing env vars.

Core principle: investigate first, ask later. Never tell the user to run a command you can run yourself. Read .env files, run docker compose ps, and check logs yourself before reporting.

Step 0 — Preconditions

1. Verify you are inside a notom-platform worktree or the main project (presence of docker-compose.yml at the worktree root).
2. Verify docker / docker compose is available.
3. Read ../../shared/infra-map.md — the single source of truth for machine-specific paths (e.g. ROOT_ENV). Substitute its values wherever a step references an infra-map key.

Step 1 — Classify the symptom

Inspect what the user reported (start from $ARGUMENTS when non-empty) and route:

• Env var missing → Step 2a
• Service not reachable / auth redirect failing → Step 2b
• Auth/OIDC error (client_id missing, JWKSInvalid, invalid_grant) → Step 2c

Step 2a — Missing env var (e.g. VITE_API_URL, AUTHENTIK_ISSUER_URL)

1. Read apps/atlas/api/src/env.ts or apps/atlas/app/src/env.ts to see what's required.
2. Read the root .env (source of truth) for the values — path: ROOT_ENV, see infra-map.
3. Write the missing .env file:
   • API .env (apps/atlas/api/.env) gets backend vars copied from root .env.
   • App .env (apps/atlas/app/.env) gets only VITE_* vars + VITE_API_URL.

Worktrees don't inherit .env from the main project — create them explicitly.

Step 2b — Service not reachable / auth redirect failing

1. Check which containers are up and healthy — start from the Docker snapshot in ## Context; re-run docker compose ps if it shows docker unavailable or may be stale. Services: postgres, redis, authentik-server, authentik-worker.
2. If Authentik missing:

   docker compose --env-file "<ROOT_ENV — see infra-map>" up -d authentik-server authentik-worker
   

   Authentik takes ~60s to start. Re-check with docker compose ps.
3. docker compose logs --tail=30 authentik-server authentik-worker — check for crashes.

Step 2c — Auth / OIDC failures

Step 3 — Fix or instruct

Apply the fix yourself when possible (write .env, start containers). Only instruct the user for actions you genuinely cannot perform (e.g. clicking in the browser, running moon run db-platform:setup_dev which requires interactive context).

Infrastructure map (reference)

Final report

stack-golem:debug-local report
  Symptom:      <classified symptom>
  Investigated: <docker compose ps / .env reads / logs checked>
  Root cause:   <diagnosis>
  Action:       <what was fixed / what the user must do>

Hard rules

• Always run docker compose ps yourself before reporting container status.
• Always read .env files yourself before saying they're missing.
• Check logs yourself (docker compose logs) before asking the user.
• Never git commit, git push, or git rebase.
• Worktrees don't inherit .env — create them explicitly.