59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
---
|
|
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.
|