docs: a PR body is history too — findings belong in issue bodies, and a PR that finishes a ticket says Closes - #423
Merged
Conversation
The Issue Hygiene section already said "the body is the finding, a comment is not." It said nothing about PR bodies or commit messages, so this session obeyed the letter and broke the rule anyway: four findings went into PR bodies and commits, which are one level further from a reader than the comments the rule bans. Two additions: - a PR body and a commit message are history; a finding that outlives the PR belongs in an issue body (#421, #422 are the two filed as a result) - a PR that finishes a ticket says `Closes`, not `Refs`. #381, #382 and #383 sat open behind their own merged PR, reading as pending work that had already shipped.
.gitignore had no backup pattern at all — no *.bak, *.orig, *.rej, *~, *.swp. A CLAUDE.md.bak-2026-07-28 left over from the #417 session was sitting in the repo root as untracked-but-not-ignored, one `git add -A` from being committed. It was a strict subset of the current CLAUDE.md, so it was deleted rather than kept. Nothing has slipped through yet. Closing it anyway because this repo has been bitten by the same shape once already: #392, where a local root build rewrote public/manifest.json and the mitigation was "remember not to stage everything". Verified the patterns catch real backups, and that no tracked file is shadowed by them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The rule had a hole, and I fell through it
CLAUDE.md's Issue Hygiene section says "the issue BODY is the finding. A comment is not." It says nothing about PR bodies or commit messages.So this session obeyed the letter and broke the rule anyway. Four real findings from the 3a–3d reskin went into PR bodies and commit messages — which are one level further from a reader than the comments the rule already bans. Nobody greps merged PRs to learn how the system works today.
What that cost, concretely:
|on prod. That finding existed only in PR feat(#380): apply 3a to /docs — the docs render in the app #420's body and a code comment. Now Blog posts render tables as literal pipes: the markdown processor has no table or blockquote support, and 2 published posts are affected #421./themesAA/AAA badges were dropped for a measured reason that lived only in a code comment. Now Per-theme AA/AAA badges on /themes have no data to render from: 32 themes have no AAA verdict and the 34-theme guard only covers embed colors #422./docs— the claim probing disproved. Left alone it would have sent the next reader down the path I rejected. Struck and corrected.Refs, notCloses.The change
Two bullets in the Issue Hygiene list:
Closes #N, notRefs #NBoth cite the specific issues that prompted them, so the rule carries its own evidence rather than reading as a preference.
Also in here: the litter that prompted half of it
Checking the tree for stray work turned up
CLAUDE.md.bak-2026-07-28(23KB) sitting untracked in the repo root from the #417 session — and.gitignoreturned out to have no backup pattern at all: no*.bak,*.orig,*.rej,*~,*.swp. Onegit add -Awould have committed it.Nothing has slipped through yet, but this repo has already been bitten by the same shape once — #392, where a local root build rewrote
public/manifest.jsonand the only mitigation was remembering not to stage everything. The.gitignorerule is the version that does not depend on remembering.The backup file was a strict subset of the current
CLAUDE.md, so it was deleted rather than kept. Verified the new patterns catch real backups, and that no tracked file is shadowed by them.Docs and ignore rules only; no code paths touched.
Closes #424. Refs #376.