# Debug Local

> Use when the user reports a runtime error, a service not starting, an auth/OIDC failure, or missing env vars in local dev on the notom platform. Investigate proactively with available tools before asking the user to run anything.

- Skill: `g-bastianelli/debug-local` (Agent Skill)
- Install (CLI): `npx skillmds@latest add g-bastianelli/debug-local`
- Raw SKILL.md: https://api.skillmd.com/api/skills/g-bastianelli/debug-local/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: g-bastianelli (https://skillmd.com/u/g-bastianelli)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/g-bastianelli/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:
   ```bash
   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

| Symptom                                 | Diagnosis                                                   | Fix                                                                                   |
| --------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `client_id is missing or invalid`       | Authentik is fresh — `atlas-dev` OAuth client doesn't exist | `moon run db-platform:setup_dev` from the **project root** (NOT the worktree)         |
| `JWKSInvalid` / token validation failed | Race on first load — JWKS cache not warm                    | Hard-refresh the page; if it persists, check Authentik health via `docker compose ps` |
| `invalid_grant` on refresh              | Old refresh token from a previous session                   | Normal — frontend redirects to login automatically                                    |

## 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)

| What                          | Where                                                         |
| ----------------------------- | ------------------------------------------------------------- |
| Docker Compose                | `docker-compose.yml` at worktree root                         |
| Root `.env` (source of truth) | `ROOT_ENV` — see `../../shared/infra-map.md`                  |
| API `.env`                    | `apps/atlas/api/.env` — copy vars from root `.env`            |
| App `.env`                    | `apps/atlas/app/.env` — only `VITE_*` vars + `VITE_API_URL`   |
| Authentik setup               | `moon run db-platform:setup_dev` — creates `atlas-dev` client |

## 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.