home-services/.claude/skills/readme-drift-check/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
readme-drift-check	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.	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.