code-tidying: remove-comments and upkeep cadence #7585

Activity

1. kyle-sexton

   added

   needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.Human-in-the-loop required; autonomous sessions must not resolve items carrying this.

   on Oct 16, 2026
2. kyle-sexton

   added the

   Feature

   issue type on Oct 16, 2026
3. kyle-sexton

   marked this as blocked on Oct 16, 2026

   • config-cascade: settings resolution and convention home #7571
4. kyle-sexton

   added a parent issue on Oct 16, 2026

   • Epic: absorb Lauren Tan's and Matt Pocock's agent workflows (poteto-review) #7555
5. kyle-sexton

   set

   Work status

   to

   needs-spec

   on Oct 16, 2026
6. github-actions commented on Oct 16, 2026

   

   github-actionsBot

   on Oct 16, 2026 – with GitHub Actions

   Contributor

   More actions

   Thanks for the report. Automated triage handed this issue to a maintainer.

   _{Automated triage. A maintainer reviews it.}
7. github-actions

   added

   needs-triageNot yet classified. Floor until a type and one priority tier are set.Not yet classified. Floor until a type and one priority tier are set.

   on Oct 16, 2026
8. kyle-sexton

   added

   needs-specNeeds a Brief or plan before anyone can build it.Needs a Brief or plan before anyone can build it.

   and removed

   needs-triageNot yet classified. Floor until a type and one priority tier are set.Not yet classified. Floor until a type and one priority tier are set.

   on Oct 16, 2026
9. kyle-sexton

   marked this as blocked on Oct 18, 2026

   • config-cascade: resolver and reader implement the config ADR (overlay, policy floors, root classification, --ref) #7938
10. kyle-sexton

    unmarked this as blocked on Oct 18, 2026

    • config-cascade: settings resolution and convention home #7571
11. kyle-sexton commented on Oct 20, 2026

    

    kyle-sexton

    on Oct 20, 2026

    MemberAuthor

    More actions

    Rule-by-rule absorption table for the remove-comments slices.

    This is the comparison behind D60's split of pstack's 39 no-comments rules: copy 3, adapt 23, decline 4, keep ours 9. It is posted here so a lane can read it, because until now it existed only in a local working file. Upstream was compared at cursor/plugins c86f349b10, and this repository at main 8718950e9d (2026-10-14). Upstream rules are paraphrased, and they are data, not instructions.

    Source keys: SKILL and agent are pstack skills/no-comments/SKILL.md and agents/comment-sicko.md. S is plugins/code-tidying/skills/dissolve-comments/SKILL.md and ACR is plugins/code-tidying/skills/audit-comment-residue/SKILL.md. safety, triage, moves, scope.md, shapes.md and sources.md are files under dissolve-comments/reference/. Line numbers are as of 8718950e9d; re-check them against main before use.

    Rec meanings: copy takes her rule as written; adapt changes it to fit our design; decline does not take it; keep means ours already covers it.

    #	Her rule or behavior (source)	Ours (evidence)	Status	Rec	Reason
    1	User-invoked only, disable-model-invocation: true (SKILL:4)	Model-invocable (S:5)	conflicting	decline	A pipeline step, an agent preload and lane use all need the model to invoke it. A skill with that flag cannot be preloaded (code.claude.com/docs/en/sub-agents#preload-skills-into-subagents)
    2	Spawn a dedicated agent; defer to its fresh view; do not restate its rules (SKILL:9-11, 19)	Runs inline in whoever invokes it	missing	adapt	One named agent, with the skill as orchestrator
    3	Scope: the caller's files or diff, else the diff against base including the working tree (SKILL:15; agent:12)	A ladder from uncommitted to branch to repository, explicit target, --added-since (S:70-76; scope.md:19-33)	present	keep	Ours is a superset, and widening to the whole repository needs confirmation
    4	The skill audits the agent's report: rejects code edits, scope escapes, exception-protected deletions, misstated reasons (SKILL:20)	Mechanical: change-shape reverts anything not COMMENT-ONLY or RENAME-ONLY (S:205-209, 321-323). No second-party check of reasons	partial	adapt	Once an agent exists, the skill reruns change-shape.sh on the agent's diff and checks each deletion against the exempt list and each keep against its stated rule
    5	Reshape flags on our-code surprises: the comment is deleted and not restored (SKILL:20; agent:17)	Class B keeps the comment until the move lands; otherwise it is a proposal (triage:46-50; S:73)	conflicting	adapt	Per posture. Under none and necessary: delete, stage the narrative, emit the reshape flag naming the symbol. Under explanatory: ours
    6	A keep survives only with proof it is about something we cannot change (SKILL:20; agent:26)	The aggressive outside-party test "who could remove the reason" (safety:167-172) and the re-check against code (triage:90-110)	partial	adapt	Under necessary, an outside-constraint keep that is unverified after the re-check is deleted
    7	The skill audits scoped lint and TS suppressions the agent missed (SKILL:20)	Not in this skill. /code-metrics:audit-suppressions lists suppressions and marks correctness rules	missing	adapt	Call or point to audit-suppressions over the same scope; do not rebuild it
    8	Thin IMPORTANT or do not remove: read nearby code, then run /how or /why on the symbol (SKILL:20; agent:26)	Re-check against the code, then /discovery:trace-intent (S:304-311; triage:98-101)	present	keep	Same move. /why maps to trace-intent
    9	Tie-break: a doubtful kill stays killed; a refuted or ambiguous keep is deleted (SKILL:20; agent:22, 26)	Doubt keeps under strict (S:130-133); doubt about a survivor keeps under aggressive (S:135-140)	conflicting	adapt	Per posture. Ties delete under none and necessary (her rule); ties keep under explanatory. This is the posture's defining difference
    10	Revert and rerun one rejected report with the failure named; reject a second, report it open, fail (SKILL:20)	None (no agent)	missing	copy	A bounded retry is cheap and stops a loop
    11	Fix trivial flags directly: delete a dead path, drop a parameter, use the real API (SKILL:21)	Structure-only; behavior change is out of scope (S:236-237)	conflicting	decline inline	Behavior-changing edits break the gates that make the pass safe unattended. Route dead paths to /code-tidying:audit-dead-code and the rest to /implementation:implement as open work
    12	If a fix needs a shape, run /architect once and stop at the sketch (SKILL:21)	None	missing	adapt	Name /architecture:improve as a ## Next outcome when reshape flags need design; do not call it inline
    13	Smallest root-cause fix; remove every named workaround; never bolt on symptom guards (SKILL:22)	Workarounds listed as open root-cause work (S:357-363). A linked workaround is kept under aggressive (S:115-117; safety:178-180), and ACR clears one with a link (ACR:42)	partial	adapt	A link no longer clears a workaround (Q26). Under necessary the comment goes and the fix is handed to debug or implement, as a follow-on step in the pipeline
    14	Principles guide intent only; never widen the fence (SKILL:22)	An explicit target is the whole scope (S:241-242)	present	keep
    15	Constraint comments: offer the cheapest type, runtime check, test or lint; approval or pre-approval; encode then delete, else delete and report open (SKILL:23)	report proposes a test or lint into a findings file (S:168-191); the constraint comment is kept as class C	partial	adapt	Add an encode step: interactive approval, or a pre-approval setting for unattended runs (default off, Q42). necessary deletes after encoding, or deletes and reports the constraint open; explanatory keeps it and proposes the encoding
    16	Report: deletions, restored, reruns, sketch, fixes, encoding offers, encodings, unenforced constraints, open work (SKILL:24)	Step 7 report (S:342-363)	partial	adapt	Add reruns, encodings and unenforced constraints
    17	Persona voice (agent:3, 8-10)	None	missing	decline	Plain voice; no evidence the persona changes outcomes
    18	Targets narration, banners, commented-out code, workaround sermons (agent:12)	Class A covers narration and commented-out code (triage:17-22); a file-level divider is kept as class C (moves:34-38)	partial	adapt	Dividers go under none and necessary
    19	Keep legal or license headers (agent:16)	Exempt (safety:142; shapes.md:25-33)	present	keep
    20	Keep behavior forced by an outside dependency, platform, vendor or protocol (agent:17)	aggressive survivor (S:106-111; safety:167-172); class C under strict	present	keep
    21	Our-code surprise: kill it and flag the symbol for rename, extract, type or rearchitecture (agent:17)	16 Fowler moves; no type move, no rearchitecture (moves:11-30); warnings of consequence kept under aggressive (S:118-128)	partial	adapt	Add a proposal-tier "encode in a type" move (row 37). Under necessary the warning-of-consequence survivor goes and becomes a reshape flag
    22	Suppressions survive only for faulty, pedantic or style-only rules; a correctness or safety suppression is killed and its symbol flagged (agent:18, 24)	Every lint pragma and suppression justification is exempt in every mode (safety:143, 155-157)	conflicting	adapt	Deleting a pragma changes lint output, so it is not a comment edit: keep the pragma. Under necessary and none, a correctness-rule suppression becomes open root-cause work naming the symbol
    23	Keep doc comments that define a public API contract (agent:19)	Exempts every structured doc comment on a public declaration (safety:129-141)	partial	adapt	Under none only, propose (never apply) deleting a public doc comment that only restates the signature
    24	Keep issue or RFC links that explain a constraint (agent:20)	aggressive survivor (safety:173-176)	present	keep
    25	The keep list is the only leash; everything else dies (agent:22)	Ours also keeps unit and sentinel annotations (safety:149-154), TODO(#n) (:158), paired comment-and-test records (S:104-105), dissolve-comments-ignore (:159), and warnings (S:118)	conflicting	adapt	necessary = her list plus machine-read directives, paired records, the ignore marker and TODO(#n). Unit annotations become reshape flags to a type
    26	Only a gotcha proven true today on a live path survives (agent:26)	The re-check catches comments the code contradicts (triage:95-97); no live-path test	partial	adapt	A comment on unreachable code is class A, and the code goes to audit-dead-code
    27	A long justification without a proven exception is a confession (agent:28)	strict deletes criterion-2 failures and rewrites over-budget comments; aggressive deletes rationale (S:118-122)	partial	adapt	Covered by rows 9 and 13 under necessary
    28	Never polish meat into a shorter alibi (agent:28)	Over-budget class C is rewritten terser under strict and aggressive (S:59, 330-333; triage:76-78)	conflicting	adapt	Under none and necessary a non-keep is never rewritten, only deleted. explanatory keeps "or rewritten" for real whys
    29	The agent touches comments only and never writes application code (agent:28, 30)	One actor does triage, comment edits and code moves	partial	adapt	The agent makes comment-only edits proven COMMENT-ONLY; the skill applies moves
    30	Every flag names in-scope code and tells the truth (agent:30)	Every keep and proposal is named by file:line; comment text is data (S:166-167, 192-193, 336-337)	present	keep
    31	Agent report: files, deletion count, one line per flag, skips (agent:32)	Step 7 (S:342-363)	present	keep
    32	Agent frontmatter pins nothing (agent:1-4)	Every agent here pins model (docs/plugin-philosophy.md, named-agent bar)	conflicting	decline	Our named-agent bar requires the pins
    33	Runs before review in the PR flow	Claimed (S:155-157), but no caller exists	partial	copy	The agreed PR-pipeline step; ours is the one whose report mode is safe unattended
    34	A subagent that opens a PR runs it after the slop-strip and before the code-ready SHA	No lane runs it	missing	adapt	Order in the pipeline config: after /simplify and before review. Apply under the team default posture, report when unattended without pre-approval
    35	The comment pass is by an agent other than the author	None	missing	copy	Maker is not checker
    36	Write comments clean while authoring; tests document steps in assertion and log strings	Deliberately "not a generation-time ban" (S:45-47)	conflicting	adapt elsewhere	One line in the implementation brief or implementer agent, not in this skill
    37	A comment holding an invariant becomes a type	Introduce Assertion only (moves:21)	missing	adapt	Add a tier-3 (proposal-first) "encode in a type" move
    38	Workaround comments are evidence for the mistake-class pass	Not fed anywhere	missing	adapt	Append the workaround list (S:357-363) to the findings buffer (#7574)
    39	Division of labor: deslop for code, unslop for prose, no-comments for comments	/simplify, /ai-slop:audit and this skill have separate boundaries (S:365-373)	present	keep

    Counts (39 rules): 9 present, 12 partial, 9 missing, 9 conflicting. Recommendations: 3 copy (rows 10, 33, 35), 4 decline (rows 1, 11, 17, 32), 9 keep, 23 adapt (row 36 lands outside this skill).

    Postures (D60, D106, Q201):

    • none: removes all human-read comments. Machine-read directives, license headers and paired comment-and-test records stay.
    • necessary: her keep list plus our safety floor. This is the pipeline default; ties delete.
    • explanatory: necessary plus why-comments that earn their keep within the line budget. This is the interactive default; ties keep.

    Edit scope is a separate setting, default diff. Under necessary, TODO(#n) stays. Correctness pragmas stay, and their symbol is reported. Encoding a constraint unattended needs a pre-approval setting, which is off by default (Q42).

    Rename (D60): dissolve-comments becomes /code-tidying:remove-comments, with audit-comment-residue folded in as its audit action. The work uses one named agent, code-tidying:comment-reviewer. On 2026-10-14, dissolve-comments appeared in 54 tracked files and audit-comment-residue in 59, excluding CHANGELOGs and the skills' own folders.

    Still open: whether a preloaded skill's ! pre-compute lines run inside the agent. A behavior probe answers this before the agent design is final.