Skip to content

docs: correct ARCHITECTURE.md against the code, link the README badges - #21

Merged
KristofferRisa merged 1 commit into
mainfrom
docs/accuracy-pass
Aug 28, 2026
Merged

docs: correct ARCHITECTURE.md against the code, link the README badges#21
KristofferRisa merged 1 commit into
mainfrom
docs/accuracy-pass

Conversation

@KristofferRisa

Copy link
Copy Markdown
Owner

Two parts: a factual audit of the docs, and the README badge update.

The docs described behaviour that does not exist

I checked each claim against the source instead of editing around it. Four were wrong:

Claim Reality
"Reconnection: Exponential backoff (max 5 retries)" and "Heartbeat: 30-second ping interval" Neither exists. grep -riE "reconnect|backoff|retry|ping|heartbeat" internal/ returns nothing outside tests. websocket.go has five functions and none of them reconnect.
README: "WebSocket auto-reconnects on temporary failures" Same fiction, user-facing — and more wrong after #17, which made a parse error end the stream.
"No Pulse — Exit 2 with Pulse not enabled" Nothing exits 2. Every error path goes through exitWithError, which is os.Exit(1).
Dependency table: nhooyr/websocket go.mod has github.com/coder/websocket v1.8.15 — the package was renamed.

The reconnect one is the reason this is worth doing: someone reading Troubleshooting would wait for a recovery that is never coming. Both spots now say the stream ends and exits 1, and suggest a supervisor if you need it to stay up.

Also stale, less severely:

  • Formatter interface was missing FormatConsumptionHistory (added in feat: implement consumption history command #12)
  • Directory tree missing consumption.go, every _test.go, CONTEXT.md, .goreleaser.yml
  • build-all snippet showed a PLATFORMS loop the Makefile does not have
  • Testing Strategy omitted websocket_test.go
  • Title said "Tibber CLI"; the project, module and binary are all powerctl

Release pipeline was undocumented

Tagging is the only way to ship, and neither ARCHITECTURE.md nor CONTRIBUTING.md said so. ARCHITECTURE.md gains a Release Pipeline section; CONTRIBUTING.md gains a Releasing section with the tag commands, the dry-run that renders notes without publishing, and how the changelog grouping behaves.

Badges

They were bare <img> tags that linked nowhere. Now:

  • release → links to /releases/latest
  • release notes → new, links to /releases
  • tests → pinned to ?branch=main, links to the workflow
  • license → links to LICENSE

All four verified to return 200 with live values (release: v0.4.2, release notes: today, tests: passing, license: MIT) rather than assumed.

Verification

  • make check passes
  • Every relative link across README, CONTRIBUTING, ARCHITECTURE and CLAUDE.md resolves to a file that exists
  • User-Agent: powerctl-cli/1.0 claim confirmed against websocket.go:18 before documenting it

No code changes.

⚡ Built on gilfoyle with Claude Code

ARCHITECTURE.md had drifted from the implementation. Verified each claim
against the source rather than editing around it:

- WebSocket client claimed "Reconnection: Exponential backoff (max 5 retries)"
  and "Heartbeat: 30-second ping interval". Neither exists — there is no
  reconnect, backoff, retry or ping anywhere in internal/. README repeated the
  same claim in Troubleshooting. Both now say what actually happens: the stream
  ends and exits 1.
- "No Pulse | Exit 2" — nothing in the codebase exits 2. Every error path goes
  through exitWithError, which exits 1.
- Dependency table listed nhooyr/websocket; go.mod has coder/websocket v1.8.15.
- Formatter interface was missing FormatConsumptionHistory.
- Directory tree was missing consumption.go, every _test.go file, CONTEXT.md
  and .goreleaser.yml.
- The build-all snippet showed a platform loop the Makefile does not have.
- Testing Strategy omitted websocket_test.go.
- Title said "Tibber CLI"; the project, module and binary are powerctl.

Also documents the release pipeline, which was undocumented in both
ARCHITECTURE.md and CONTRIBUTING.md despite being the only way to ship.

README badges were bare images that linked nowhere. They are now links, the
tests badge is pinned to main, and a release-notes badge points at the
releases page. All four URLs verified to return 200 with live values.
@KristofferRisa
KristofferRisa merged commit ee471ad into main Aug 28, 2026
5 checks passed
@KristofferRisa
KristofferRisa deleted the docs/accuracy-pass branch August 28, 2026 16:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant