---
name: readme-drift-check
description: Audit each service README (ha-gateway, ai-gateway, discord-bot) against the actual code — env var tables vs config.go, Implemented/Stubbed RPC lists vs proto and adapter code, and Package Map vs the real directory tree. Reports drift without editing anything.
disable-model-invocation: true
---

# README Drift Check

This repo documents contracts by hand in three READMEs (`ha-gateway/README.md`,
`ai-gateway/README.md`, `discord-bot/README.md`), and those have gone stale before
(e.g. `OLLAMA_TIMEOUT`'s default needed a manual doc update after a config change). This
skill finds the next drift before it ships. **Read-only** — report findings, do not edit
README or code unless the user asks you to apply a fix afterward.

## Checks, per service

### 1. Environment variable table vs `internal/config/config.go`

- Read the Configuration table in the service's README.
- Read `internal/config/config.go` and find every env var read (`os.Getenv`,
  `os.LookupEnv`, or equivalent helper) plus its default.
- Flag: vars in code missing from the README table, vars in the README table no longer
  read in code, and default values that don't match.

### 2. Implemented / Stubbed RPC list vs actual server code

- Read the gRPC API section's Implemented/Stubbed split in the README.
- Read the corresponding `proto/<pkg>/v1/*.proto` for the full RPC list.
- Read `internal/adapters/primary/grpc/*.go` and check each method body: a method that
  just returns `status.Errorf(codes.Unimplemented, ...)` (or equivalent) is Stubbed;
  anything else is Implemented.
- Flag: any RPC whose README status doesn't match what the code actually does, and any
  RPC in the proto missing from the README entirely.

### 3. Package Map vs real directory tree

- Read the Package Map section in the README.
- Run `find <service>/internal -type d | sort` (and `cmd/`) and compare.
- Flag: directories that exist but aren't documented, and documented paths that no longer
  exist.

## Output

Report per service, grouped by check, e.g.:

```
## ha-gateway
### Env vars
- MISSING FROM README: `NEW_VAR` (default "x") — read in config.go:42
### RPC status
- README says `SwitchService.TurnOn` is Stubbed, but internal/adapters/primary/grpc/switch.go:18
  now implements it — README is stale.
### Package map
- OK
```

If everything matches for a service, say so briefly rather than listing every checked
item — don't pad the report with confirmations of things that are fine.