You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A new comment-residue skill in the code-tidying plugin: a read-only classifier that flags out-of-context residue in code comments and presents Tier 1/2 findings for author-applied deletion. Mirrors declutter's architecture (detect.sh + sourceable shape library + self-contained detect.test.sh), but scans code files and detects only on the comment portion of a line.
Residue shapes:history-narration ("used to… now…"), plan-reference ("Task 2 replaces the old…", "in this PR"), conversational-antecedent ("per your request") — all Tier 1; ticket-pr-residue ("see PR #45", "JIRA-123") — Tier 2. TODO(#issue) is the sanctioned back-reference and is never flagged.
Bumps code-tidying 0.2.0 → 0.3.0; documents the skill in the manifest + README catalog.
Why
Agents leak the producing conversation/plan/history into comments — text that only makes sense inside the chat thread that wrote it. No existing skill targets this: declutter is markdown-only, compress excludes code comments, and tidy's Beck-#15 handles generic restatement, not the out-of-context residue class. This is the clean-up-afterward companion to the source-side comment rule (a separate dotfiles-repo change).
Design notes
Comment-scoped detection — residue-shaped words in identifiers or string literals (previously = load_cache(), # encode as UTF-8 / SHA-256) are not flagged; only the comment text is classified. This keeps false positives low; anything uncertain lands in Tier 2 (review), and the skill is read-only so the author confirms every deletion.
Placement — filed under code-tidying (subject = code) per the plan. It's a read-only classifier like declutter (which lives in docs-hygiene), so a mode-based argument for docs-hygiene exists; flagging for reviewer preference.
Security review (plugin-acceptance)
Touches only surface 1 — a read-only, advisory detect.sh (spawns git/find/awk, never mutates, no network, no MCP server, no userConfig/secrets, reads only files under the invoking repo via ${CLAUDE_PLUGIN_ROOT} / git rev-parse). No surface 2/5/6 trust decision required.
Test plan
detect.test.sh — 19/19 (shapes, tiers, opt-out, markdown-skip, dir + paths-file, and the false-positive guards: code identifier, UTF-8/SHA-256, sanctioned TODO(#123))
Low Risk
Read-only local bash/git scanning with no mutations, secrets, or network; CI change is a targeted hygiene exclude for test/detector content.
Overview
Adds /code-tidying:comment-residue, a read-only skill that audits code comments for four residue shapes (history narration, plan/session refs, conversational antecedents, ticket/PR back-refs) and reports Tier 1/2 findings with treatment guidance—authors apply deletions; no edits from the skill.
Implementation follows the declutter-style split: detect.sh (targets, git default, deterministic output), lib/comment-shapes.sh (comment-only extraction with string-aware leaders, shape regexes, sanctioned TODO(#issue), comment-residue-ignore), plus detect.test.sh, eval fixtures, and evals.json. code-tidying bumps to 0.3.0; README and manifest copy describe comment hygiene alongside tidy / batch-simplify.
CI comment-hygiene now excludescomment-residuescripts and evals so intentional TODO/PR-shaped test corpus and detector patterns do not trip the repo ban policy.
Reviewed by Cursor Bugbot for commit 43f7bfa. Bugbot is set up for automated code reviews on this repo. Configure here.
Add a comment-residue skill that classifies code comments for four
out-of-context residue shapes — history-narration, plan-reference,
conversational-antecedent (Tier 1), and ticket-pr-residue (Tier 2) —
emitting per-file tier findings for author-applied deletion. It mirrors
declutter's read-only classifier architecture (detect.sh + a sourceable
shape library + self-contained tests), but scans code files instead of
markdown and runs detection only on the comment portion of a line, so
residue-shaped words in identifiers or string literals are not flagged.
TODO(#issue) is the sanctioned back-reference and is never flagged.
Bump code-tidying to 0.3.0 and document the skill in the plugin manifest
and README catalog.
Security review (plugin-acceptance): touches only surface 1 — a
read-only, advisory detect.sh that spawns git/find/awk, never mutates,
never networks, ships no MCP server, declares no userConfig or secrets,
and reads only files under the invoking repo via ${CLAUDE_PLUGIN_ROOT} /
git rev-parse. No surface 2/5/6 trust decision required. Validated:
shellcheck, shfmt, markdownlint, detect.test.sh (19/19), and
claude plugin validate --strict.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rC4MXTWrQZJXG7GRtsX4K
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot completed with status skipping (usage limit reached) and did not produce a clean review. Human review is needed before merge; no reviewers were assigned because no suitable non-author reviewers were identifiable from repo history.
Sent by Cursor Approval Agent: Pull Request Router and Approver
The comment-residue skill is itself a code-comment linter: its detector
fixtures and shape library must contain the markers the org
comment-hygiene policy bans (TODO/FIXME and PR/issue references) — as
test corpus and as the documented TODO(#issue) sanctioned exemption.
Exempt that skill's scripts and evals via the action's exclude pathspec.
Reproduced the 7 violations locally and confirmed the exclude clears
them; the skill's SKILL.md is markdown, already outside the scan's
extension set.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rC4MXTWrQZJXG7GRtsX4K
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot completed with status skipping (usage limit reached) and did not produce a clean review. Human review is needed before merge; no reviewers were assigned because no suitable non-author reviewers were identifiable from repo history.
Sent by Cursor Approval Agent: Pull Request Router and Approver
…ings
Address three chatgpt-codex-connector review findings on the
comment-residue classifier:
- Comment-scoped detection (comment-shapes.sh): cr_comment_text now scans
the line as a mini-lexer that tracks "...", '...', and `...` spans and
only treats a leader (//, /*, #, --) as a comment start when it is
OUTSIDE a string. A residue-shaped phrase inside a URL or string
literal (e.g. "https://x/used to do X; now does Y") is no longer
mis-read as history-narration, honoring the skill's comment-scoped
contract. Apostrophes in comment prose ("it's no longer used") are not
treated as strings because the leader is found first, so genuine
residue is still flagged. Replaces the prior "approximate, harmless"
extractor whose stale rationale the counterexample disproved.
- ticket-pr-residue (comment-shapes.sh): the branch now also matches the
bare hyphenated tracker key form the docs advertise (JIRA-123), not
only "<tracker> <num>". Scoped to the enumerated tracker vocabulary
(ticket|issue|jira|linear) so UTF-8 / SHA-256 stay unflagged.
- --paths-file guard (detect.sh): reject a missing value with exit 2.
Previously an omitted value left one positional, `shift 2` failed
under `set +e`, and the arg loop spun forever; a typo could hang the
skill invocation.
Add fixtures covering all three (string-aware extraction, bare JIRA-123,
missing-value guard). detect.test.sh 24/24, shellcheck and shfmt clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gKgRoW8zkFadbE2hE4r4b
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot completed with status skipping (usage limit reached) and did not produce a clean review. Human review is needed before merge; no reviewers were assigned because no suitable non-author reviewers were identifiable from repo history.
Sent by Cursor Approval Agent: Pull Request Router and Approver
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Risk: medium. Not approving: Cursor Bugbot completed with status skipping (usage limit reached) and did not produce a clean review. Human review is needed before merge; no reviewers were assigned because no suitable non-author reviewers were identifiable from repo history.
Sent by Cursor Approval Agent: Pull Request Router and Approver
detect.sh cd's to the repo root before resolving caller-supplied paths, so
an explicit relative target or --paths-file value given from a subdirectory
(e.g. `detect.sh rel.py` run from `src/`) resolved against the repo root and
silently reported files=0. Capture the invocation cwd and anchor explicit
positional targets, the --paths-file path, and its relative line entries to
it before the cd; git-status discovery stays repo-relative by design.
Add regression coverage: relative target and relative --paths-file invoked
from a repo subdirectory. detect.test.sh 27/27, shellcheck clean.
Addresses the remaining chatgpt-codex-connector finding on detect.sh.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013gKgRoW8zkFadbE2hE4r4b
The reason will be displayed to describe this comment to others. Learn more.
Risk: medium. Not approving: Cursor Bugbot completed with status skipping (usage limit reached) and did not produce a clean review. Human review is needed before merge; no reviewers were assigned because no suitable non-author reviewers were identifiable from repo history.
Sent by Cursor Approval Agent: Pull Request Router and Approver
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
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.
What
A new
comment-residueskill in the code-tidying plugin: a read-only classifier that flags out-of-context residue in code comments and presents Tier 1/2 findings for author-applied deletion. Mirrorsdeclutter's architecture (detect.sh+ sourceable shape library + self-containeddetect.test.sh), but scans code files and detects only on the comment portion of a line.Residue shapes:
history-narration("used to… now…"),plan-reference("Task 2 replaces the old…", "in this PR"),conversational-antecedent("per your request") — all Tier 1;ticket-pr-residue("see PR #45", "JIRA-123") — Tier 2.TODO(#issue)is the sanctioned back-reference and is never flagged.Bumps code-tidying
0.2.0 → 0.3.0; documents the skill in the manifest + README catalog.Why
Agents leak the producing conversation/plan/history into comments — text that only makes sense inside the chat thread that wrote it. No existing skill targets this:
declutteris markdown-only,compressexcludes code comments, andtidy's Beck-#15 handles generic restatement, not the out-of-context residue class. This is the clean-up-afterward companion to the source-side comment rule (a separate dotfiles-repo change).Design notes
previously = load_cache(),# encode as UTF-8 / SHA-256) are not flagged; only the comment text is classified. This keeps false positives low; anything uncertain lands in Tier 2 (review), and the skill is read-only so the author confirms every deletion.code-tidying(subject = code) per the plan. It's a read-only classifier likedeclutter(which lives indocs-hygiene), so a mode-based argument fordocs-hygieneexists; flagging for reviewer preference.Security review (plugin-acceptance)
Touches only surface 1 — a read-only, advisory
detect.sh(spawns git/find/awk, never mutates, no network, no MCP server, nouserConfig/secrets, reads only files under the invoking repo via${CLAUDE_PLUGIN_ROOT}/git rev-parse). No surface 2/5/6 trust decision required.Test plan
detect.test.sh— 19/19 (shapes, tiers, opt-out, markdown-skip, dir + paths-file, and the false-positive guards: code identifier,UTF-8/SHA-256, sanctionedTODO(#123))claude plugin validate --strict .passed🤖 Generated with Claude Code
Note
Low Risk
Read-only local bash/git scanning with no mutations, secrets, or network; CI change is a targeted hygiene exclude for test/detector content.
Overview
Adds
/code-tidying:comment-residue, a read-only skill that audits code comments for four residue shapes (history narration, plan/session refs, conversational antecedents, ticket/PR back-refs) and reports Tier 1/2 findings with treatment guidance—authors apply deletions; no edits from the skill.Implementation follows the
declutter-style split:detect.sh(targets, git default, deterministic output),lib/comment-shapes.sh(comment-only extraction with string-aware leaders, shape regexes, sanctionedTODO(#issue),comment-residue-ignore), plusdetect.test.sh, eval fixtures, andevals.json. code-tidying bumps to 0.3.0; README and manifest copy describe comment hygiene alongsidetidy/batch-simplify.CI comment-hygiene now excludes
comment-residuescripts and evals so intentional TODO/PR-shaped test corpus and detector patterns do not trip the repo ban policy.Reviewed by Cursor Bugbot for commit 43f7bfa. Bugbot is set up for automated code reviews on this repo. Configure here.