From b89fc4097abc0354b28d467aa02c2152e337a977 Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Wed, 12 Aug 2026 18:34:46 +0200 Subject: [PATCH] docs(comments-clean): bound what the audit is allowed to destroy The audit deletes comments, and nothing stopped it from taking live code or the operator index along. A line filter over nginx.conf.j2 removed a lone `#}`; the still-open `{#` then swallowed both map directives the edit was meant to add, the comment lint reported `2 passed` over the result, and Jinja parsed it without complaint. Two green signals, one silently disabled config. Block-comment languages are now excluded from line filtering, with a delimiter count and a re-parse when a block is removed by hand. Verification moves from "the lint is green" to a diff against `git show HEAD:`, because a swallowed block stays syntactically valid. Staging is no longer a precondition for running a check: only an untracked NEW file is invisible to a `git ls-files` walk, so staging a tracked, modified file changes nothing except an index the operator then has to undo. The re-stage clause from the old step 3 survives at the end of step 5, now scoped to exactly the files that were staged before the audit. Co-Authored-By: Claude Opus 5 (1M context) --- skills/comments-clean/SKILL.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/skills/comments-clean/SKILL.md b/skills/comments-clean/SKILL.md index cfa2ec7..a1cca20 100644 --- a/skills/comments-clean/SKILL.md +++ b/skills/comments-clean/SKILL.md @@ -23,9 +23,26 @@ added lines only) and delete every explanatory comment: 2. Keep only: parameter/exit-code docs, nocheck/noqa/shellcheck directives, and project-sanctioned exception markers that name a concrete trip-wire. A relabeled narration is not an exception; delete it instead. -3. Re-run the project's comment lint if one exists and re-stage the files - that were already staged. -4. Penalty: if this audit finds anything you wrote yourself, admit it in +3. Block-comment languages are not line-oriented. In Jinja (`{# … #}`), C-like + (`/* … */`), HTML (``) and their kin, a closing delimiter alone on + its own line looks exactly like a comment line and gets deleted with the + rest — after which the opening delimiter swallows every live statement down + to the next closer. Never strip these languages with a line filter. Delete + the whole block by hand, then count the delimiters (`grep -c '{#'` against + `grep -c '#}'`) and re-parse the file. +4. Re-run the project's comment lint if one exists. A green lint does NOT prove + the deletion was safe: a swallowed block is still syntactically valid, so + both the lint and the language parser can pass over code that no longer + executes. Diff against the pre-edit revision (`git show HEAD:`) and + confirm that only comment lines left. +5. Do not stage in order to run a check. Repository lints that enumerate through + `git ls-files` already see every tracked file and read its worktree content; + only an untracked NEW file is invisible to them and needs `git add`. Staging + a tracked, modified file before a lint changes nothing except the operator's + index, which they then have to undo. Stage only what a requested bundle + contains, and re-stage after the audit exactly the files that were staged + before it. +6. Penalty: if this audit finds anything you wrote yourself, admit it in the report (file and count, no excuses), lower your confidence numbers for the affected bundle, and write the incident to persistent agent memory (extend the existing minimal-comments feedback entry with the