The audit-docs skill deleting private comments

.claude/rules/docs-authoring.md

@@ -14,7 +14,7 @@ When creating or editing any markdown file, follow the discipline below. These a
 - **Prove it.** Before writing any technical claim, know the exact file (and ideally lines) that prove it. If you can't, don't write it. Silence beats speculation: no "appears to", "should", "will", or planned/intended behaviour.
 - Fix existing statements that contradict the code.
 - **Cut a comment by whole sentences, above the public floor.** Never delete or cut below one sentence the documentation comment on a public or exported symbol, a public structure member, or a package or module. Keep the sentence saying what it does, even where it restates the name, code, or syntax; where unclear, keep the first sentence. Correct a wrong or absent-content claim from the body. If the body was not read, keep the comment and report it. Cut other sentences that restate code, re-describe documented members, or narrate alternatives or reasoning where the code needs only the conclusion, keeping every other sentence word for word. A package or file comment says what the unit is for and never tours its members.
-- **Current state only.** Describe the code as it is now, in prose and in comments alike. Never narrate the past ("replaces", "used to", "formerly", "for the first time", "unlike the old") and never name a file, flag, or tool that no longer exists. Future intent lives in a `TODO` in the code, never in the documentation. **Name the line a comment describes.** Where no line corresponds, correct a public or exported symbol's comment from its body; delete an internal comment on that ground. A note about a deliberate omission the code depends on and a file header pass this test. Rationale worth keeping goes in a decision record of its own under [`docs/`](../../docs/index.md).
+- **Current state only.** Describe the code as it is now, in prose and in comments alike. Never narrate the past ("replaces", "used to", "formerly", "for the first time", "unlike the old") and never name a file, flag, or tool that no longer exists. Future intent lives in a `TODO` in the code, never in the documentation. Name the code a comment describes (a line, a block, the function, or the file); a comment giving the reason the code is written as it is passes. Where no code corresponds, correct the comment to the current fact it carries, and delete it only when none remains. An existing comment, public or private, is kept unless it is commented-out code, every sentence restates the code beneath it, or it narrates a change stating no current fact; a verbose one is tightened by whole sentences, keeping its summary and every reason, constraint, or warning, and trimming happens only inside the requested scope. A note about a deliberate omission the code depends on and a file header pass this test. An architectural or cross-cutting decision goes in a decision record of its own under [`docs/`](../../docs/index.md). The reason a particular piece of code is written as it is stays in a comment beside that code.
 
 ## Style
 

.claude/skills/audit-docs/agents/surface-auditor.md

@@ -67,7 +67,7 @@ A comment describing something the file does not contain, which the phrase list
 Response response = client.send(request);
 ```
 
-COMMENT: `Removed the manual retry loop here because the client already retries with backoff.` CODE: `Response response = client.send(request);`. **The test is to name the line the comment describes**, and here no line does: there is no retry loop in the file, so the sentence is about a decision rather than about this code. Run this test on every comment, since the sub-class above it catches only the comments that announce themselves with a banned phrase, and record the entry under `CONTRADICTED` with the absent thing named in the `BEHAVIOUR` line. Two comments pass the test and are never entries: a note about a deliberate omission the code depends on, such as why a field stays out of a payload, describes a constraint on the line beneath it; and a file-level header describes the file rather than any one line.
+COMMENT: `Removed the manual retry loop here because the client already retries with backoff.` CODE: `Response response = client.send(request);`. **The test is to name the code the comment describes**: a line, a block, the function or declaration it sits on, or the file. Here the subject is a retry loop the file does not contain, so the sentence is about a decision rather than about this code. Where a current fact remains, the caller keeps it by rewriting the comment: report it under `CONTRADICTED` with the absent thing named in the `BEHAVIOUR` line. Where no current fact remains, the closed delete list permits deletion. Run this test on every comment, since the sub-class above it catches only the comments that announce themselves with a banned phrase. These pass the test and are never entries: a comment explaining why the code beneath it is written the way it is, which describes that code; a note about a deliberate omission the code depends on, such as why a field stays out of a payload; and a file-level header, which describes the file.
 
 ## List three: comments repeated above a usage site
 
@@ -94,9 +94,9 @@ A comment can be true, non-repeated, and still carry sentences its reader does n
 
 - a sentence restating the declaration or the code beneath it, such as a signature retold in prose or a straightforward conditional, loop, or assignment walked through step by step, except for the public floor sentence, which is always kept even where it restates the name, code, or syntax;
 - a sentence listing or re-describing members that carry their own comments, which is how a package or type comment turns into a tour of the interface: each member's own comment, and the reference the language generates from them, already carry it;
-- a sentence narrating alternatives considered or reasoning walked through, where the code needs only the conclusion.
+- a sentence that only narrates alternatives or steps already captured by a later sentence, without stating a reason, constraint, edge case, or warning.
 
-Report the comment's own sentences in two verbatim sets: `KEEP`, the sentences carrying something the code does not show, and `CUT`, each sentence of the three kinds above beside the code string or member comment it restates. For a public or exported symbol, public structure member, or package or module, `KEEP` is never empty: keep its summary sentence, or the first sentence if unclear. A wrong comment in this group is corrected from the body, never deleted; an unread body means keep and report it. A sentence explaining non-obvious internal logic is also always `KEEP`. Never write replacement text: the caller writes any new wording from code it opens itself. A wrong comment also goes under `CONTRADICTED`, and the caller corrects it before cutting.
+Report the comment's own sentences in two verbatim sets: `KEEP`, the sentences carrying something the code does not show, and `CUT`, each sentence of the three kinds above beside the code string or member comment it restates. **`KEEP` is never empty for any comment reported here, public or private, documentation or inline**: keep its summary sentence, or the first sentence if unclear. This list tightens a comment and never removes one; a comment whose every sentence restates the line beneath it, with nothing kept, is outside this list and the caller judges it. A sentence giving a reason, a constraint, an edge case, a warning, or an explanation of non-obvious logic is always `KEEP`, since that is the conclusion the code cannot show. A wrong comment is corrected from the body, never deleted; an unread body means keep and report it. Never write replacement text: the caller writes any new wording from code it opens itself. A wrong comment also goes under `CONTRADICTED`, and the caller corrects it before cutting.
 
 ```python
 # We need to check if the user is eligible for the discount.
@@ -142,7 +142,7 @@ What remains is the package comment the language convention asks for: one senten
 Each of these produces noise rather than a finding, so leave each one out of the list named beside it, and only that list:
 
 - a comment that is merely terse, or plain, or worded differently from how a convention would word it: every list;
-- an internal helper whose name and signature already carry what it does: `UNDOCUMENTED`;
+- an internal helper whose name and signature already carry what it does: `UNDOCUMENTED`, since a missing private comment is not a defect. An existing comment on such a helper is still read for `CONTRADICTED` and `VERBOSE`, and its being private is never itself an entry;
 - a missing comment on a binding inside a function body: `UNDOCUMENTED`;
 - a comment sitting on a declaration: `REPEATED`, since a declaration, including an export or re-export statement, is not a use. A member's comment and a file-level header are still read for `CONTRADICTED` and `VERBOSE`;
 - a type annotation restated in prose: `CONTRADICTED`, since it is a style question and not a contradiction, though under `VERBOSE` it is a restating sentence;
@@ -189,8 +189,8 @@ BLOCKED BY: <outside the paths handed in / inside them and not opened>
 
 VERBOSE
 <file path> :: <symbol, or the line the comment sits above>
-KEEP: <each sentence carrying what the code does not show, verbatim, with any credential value replaced by [REDACTED]; never empty for a public symbol, public structure member, package, or module, where its summary sentence or, if unclear, first sentence goes here>
-CUT: <each sentence to delete, verbatim> :: <the code string or member comment it restates, verbatim, or the reasoning it narrates>
+KEEP: <each sentence carrying what the code does not show, verbatim, with any credential value replaced by [REDACTED]; never empty, with the summary sentence or, if unclear, the first sentence always here>
+CUT: <each sentence to delete, verbatim> :: <the code string or member comment it restates, or the later sentence that already states the same conclusion>
 
 COUNTS
 Files in scope: <n>

.claude/skills/audit-docs/assets/audit-report.template.md

@@ -85,7 +85,7 @@ Undocumented public symbols outside the change, listed rather than documented: [
 | `[path]` | [documented [count] previously undocumented public symbols]    |
 | `[path]` | [created, [tutorial / how-to guide / reference / explanation]] |
 
-Kinds to choose from: made the change the request asked for, corrected a factual statement, documented a public symbol, retained a public documentation comment at its one-sentence floor, corrected an existing documentation tag, removed an outdated or restating internal comment, removed a comment repeated above a usage site, cut sentences from a comment, removed a duplicated section, introduced a term on first use, added orientation for a first-time reader, created, and, only where the request asked or the user approved it, renamed, moved, split, merged, or deleted.
+Kinds to choose from: made the change the request asked for, corrected a factual statement, documented a public symbol, retained a public documentation comment at its one-sentence floor, corrected an existing documentation tag, corrected a drifted comment, removed a comment on the closed delete list (commented-out code, restating its code with nothing more, about code that no longer exists, change narration with no current fact, or a use-site comment that says no more than the declaration's comment, removed only when both sites were in scope, the declaration body was read, and any additional constraint was folded into the declaration), cut sentences from a comment, removed a duplicated section, introduced a term on first use, added orientation for a first-time reader, created, and, only where the request asked or the user approved it, renamed, moved, split, merged, or deleted.
 
 (One row per file, not one per edit. If no file changed, replace the table with "No files changed.")
 
@@ -123,6 +123,7 @@ This run edits documentation, so a code defect is reported here and left alone.
 - Every phase carries a status line, including a phase whose answer is that the documentation was already accurate.
 - Every symbol reported in Phase 3 as left as it stands because its implementation was not read also appears under Unverified.
 - No documentation comment on a public or exported symbol, public structure member, package, or module was deleted or cut below one sentence.
+- Every comment removed, public or private, documentation or inline, is on the closed delete list; every other comment was kept, corrected, or tightened by whole sentences inside the requested scope.
 - Every file changed is inside the scope, and none was renamed, moved, split, or deleted unless the request asked for it or the user approved it.
 - Every file named in a phase result appears in the files changed table, and every row of that table is a file that was edited.
 - The file count in the summary matches the number of rows in the table.

.claude/skills/audit-docs/references/existing-comments.md

@@ -0,0 +1,121 @@
+# Existing comments: correct, tighten, keep, or delete
+
+An existing comment was written by someone who knew something about the code. The audit's job is to keep that knowledge accurate, not to restyle it. Each pair below shows one outcome of the ordered tests in Phase 3: the first test that applies decides, and deletion is the narrowest outcome.
+
+- [Existing comments: correct, tighten, keep, or delete](#existing-comments-correct-tighten-keep-or-delete)
+    - [Drifted private comment: correct it](#drifted-private-comment-correct-it)
+    - [Verbose private documentation comment: tighten it](#verbose-private-documentation-comment-tighten-it)
+    - [In-body comment explaining why: keep it](#in-body-comment-explaining-why-keep-it)
+    - [Comment restating the line beneath it: delete it](#comment-restating-the-line-beneath-it-delete-it)
+    - [Change narration carrying a current fact: rewrite it](#change-narration-carrying-a-current-fact-rewrite-it)
+    - [Outcomes that are defects](#outcomes-that-are-defects)
+
+## Drifted private comment: correct it
+
+The helper is private, which is no reason to remove its comment. The comment is wrong, so it is corrected from the body, keeping the wording that is still true.
+
+Before (TypeScript):
+
+```ts
+/** Retries the request up to three times before giving up. */
+function withRetry(request: () => Promise<Response>): Promise<Response> {
+	return retry(request, { attempts: MAX_ATTEMPTS, backoffMs: 250 });
+}
+```
+
+After, where `MAX_ATTEMPTS` is `5`:
+
+```ts
+/** Retries the request up to `MAX_ATTEMPTS` times, 250 ms apart, before giving up. */
+```
+
+## Verbose private documentation comment: tighten it
+
+The summary and the constraint stay; the sentences restating the parameters and touring the body go, by whole sentences.
+
+Before (Python):
+
+```python
+def _normalize(path: str) -> str:
+    """Normalizes a path.
+
+    This helper function takes a path string as its parameter and returns
+    the normalized path string. It first strips whitespace, then lowercases
+    the value, then removes any trailing slash.
+
+    Windows drive letters are lowercased too, so callers must not compare
+    the result against a raw drive path.
+    """
+```
+
+After:
+
+```python
+def _normalize(path: str) -> str:
+    """Normalizes a path.
+
+    Windows drive letters are lowercased too, so callers must not compare
+    the result against a raw drive path.
+    """
+```
+
+## In-body comment explaining why: keep it
+
+The comment names the code beneath it and says why it is written this way, which the code cannot show. It passes the name-the-code test and states a reason, so it stays as written, however short the function.
+
+```go
+func (c *Cache) Get(key string) (Item, bool) {
+	// Read under the write lock: Get also refreshes the entry's expiry.
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.touch(key)
+}
+```
+
+## Comment restating the line beneath it: delete it
+
+Every word restates the next line and adds no reason, constraint, edge case, or warning. This is the redundant-comment ground for deletion; the other closed-list grounds also apply, subject to scope.
+
+Before (Java):
+
+```java
+// Increment counter
+counter++;
+```
+
+After:
+
+```java
+counter++;
+```
+
+## Change narration carrying a current fact: rewrite it
+
+The narration goes; the fact it carries stays, stated in the present.
+
+Before (TypeScript):
+
+```ts
+// Now uses the session token instead of the API key, which was removed.
+const headers = { Authorization: `Bearer ${session.token}` };
+```
+
+After:
+
+```ts
+// Authenticates with the session token; this endpoint rejects API keys.
+const headers = { Authorization: `Bearer ${session.token}` };
+```
+
+The rewrite keeps the claim about API keys only where the endpoint's documentation or code was opened this run. Where it was not, the comment becomes `// Authenticates with the session token.`
+
+## Outcomes that are defects
+
+Each of these removes knowledge the code does not carry, and none is on the closed delete list:
+
+- Deleting a private helper's documentation comment because the helper is private or internal.
+- Deleting every inline comment in a function because the function is short.
+- Deleting a comment explaining why because it is reasoning rather than description.
+- Replacing a verbose comment with nothing instead of cutting its padding sentences.
+- Deleting a comment you are unsure about instead of keeping it and reporting it.
+- Trimming a redundant or verbose comment outside the requested scope, where only a drifted comment is corrected.