Skip to content

docs(memory): tighten and cut comments - #694

Merged
ion-alpha-dev merged 8 commits into
mainfrom
docs/comments-memory-skill
Nov 15, 2026
Merged

ion-alpha-dev merged 8 commits into
mainfrom
docs/comments-memory-skill

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Rewrites the comments in memory, learn, skill, internal/playbook, notices, inbox, watch and jobs (65 production files) so each says something the code does not. Comment lines in scope drop from 4215 to 2152. The 31 matching lines leave internal/rigor/testdata/comment_baseline.txt.

Why

Many comments restated the code, retold history or hedged, and the comment gate baseline still listed them. Doc comments are the published API reference, so shorter ones that give the invariant, the failure guarded against or the ordering reason are easier to read on pkg.go.dev.

How to verify

Run ./dev/check. go test ./internal/rigor/... fails if a baseline line is stale or a [Name] doc link does not resolve. The diff is comment-only: scanning each changed file at the base commit and at head, with comments excluded, gives the same token stream in all 65 files.

Notes for reviewers

Every exported name keeps at least a one-line doc, because revive requires one. Test files and directives (//go:, //nolint) are untouched. Lint caught three doc comments that began "Name, ..." instead of "Name ...", and those are fixed. gofumpt also reformatted layout in memory/memory.go, skill/skillmd/skillmd.go and inbox/entry.go.

Rewrite the comments in memory, learn, skill, internal/playbook,
notices, inbox, watch and jobs so each says something the code does
not. Comments that restated the code, retold history or hedged are
deleted; the invariants, failure guards, ordering reasons, units and
doc links stay.

The diff is comment-only: the token stream of every changed file,
comments excluded, matches the base commit. The comments in scope drop
from 4215 lines to about 2150, and the matching lines leave the
comment gate baseline.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
@codecov

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
learn/regrade.go 0.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

Restore the baseline file to its base version so the branch merges
with main cleanly; the rewritten comments' entries are removed in the
next commit, on top of main's copy.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
Remove the 31 baseline entries for memory, learn, skill,
internal/playbook, notices, inbox, watch and jobs. Their comments no
longer break the gate.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
@ion-alpha-dev
ion-alpha-dev merged commit 9ccb338 into main Nov 15, 2026
33 of 34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-memory-skill branch November 15, 2026 11:02
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 15, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant