Stop diary-style Claude comments in code

Background

Comments keep appearing that describe a change rather than the code — "now refuses", "no longer", "previously", "were already … before", "Unchanged here", "Pre-existing, but…". They read as notes to the reviewer of the commit that introduced them, which is the one audience that stops existing once it merges. They also go stale silently, because nothing contradicts a claim about the past.

Two things to do.

1. Investigate how to stop them being written

Investigate creating a skill to sweep comments on current work in a branch to remove diary style comments. Resource here shared by Stu for further reading.

2. Scan the repo for existing ones

Worth covering lib/ and test/, comments and docstrings alike.

Grep alone is not enough. The obvious phrasings are easy to find, but the same habit shows up without any keyword to catch — a docstring that explains a past fix in plain prose, or one citing a function that has since been deleted. Reading the comments a given author has added, rather than pattern-matching them, finds a different and larger set.

Categories worth looking for:

• @moduledoc and @doc describing a past fix — these publish to hexdocs and IDE hover, so they are worse than an inline comment
• notes addressed to the reviewer of the commit ("Pre-existing, but…", "Inherited behaviour, not a ruling")
• references to issue or PR numbers in code
• claims about intent that nobody can actually support
• references to functions or modules that no longer exist

Out of scope

The wider question of @doc/@moduledoc volume

Start by reading comments and docstrings under lib/ and test/, especially @moduledoc and @doc entries, rather than relying only on keyword searches. Review the linked resource while investigating a branch-sweeping skill. Done means the diary-style comments found in the scan are addressed and the proposed sweep approach is documented or implemented, without expanding into general documentation-volume policy.