Skip to content

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

Open
Feature
Open
code-tidying: remove-comments and upkeep cadence#7585
Feature
Labels
needs-specNeeds a Brief or plan before anyone can build it.priority: mediumReal value, no hard deadline; normal backlog flow.status: readyTriaged, unblocked, and fully specified; eligible to pick up.work-class: structuralRefactors, migrations, contract changes; cross-cutting and hard to reverse.

Description

@kyle-sexton
kyle-sexton
opened on Oct 16, 2026

Parent

Refs #7555. Source: PLAN Phase 17, topic poteto-review. Thread: code-tidying and upkeep.

Depends on

Outcome

dissolve-comments becomes remove-comments with an audit action and one comment-reviewer agent,
under posture settings; upkeep runs as a daily batch of at most 3 PRs.

Decisions

  • Absorb Lauren's no-comments skill and agent (copy 3, adapt 23, decline 4, keep ours 9 of 39 rules);
    rename dissolve-comments to remove-comments with an audit action; one agent
    code-tidying:comment-reviewer (D60, Q39). Origin: Lauren's rules, absorbed rule by rule.
  • Postures none (opt-in), necessary (pipeline default), explanatory (interactive default); edit
    scope a separate setting, default diff; TODO(#n), license headers, comment-plus-test pairs and
    correctness pragmas per D60 (D60, D106, Q201). Setting: comment-reviewer model and effort via route
    overrides. Encoding a constraint unattended needs a pre-approval setting, default off (Q42).
  • A linked workaround comment is still a finding: fix the cause or TODO(#n) (Q26).
  • Upkeep: per-merge detection only; a daily batch of upkeep PRs; churn-triggered area sweeps; weekly
    backstop; at most 3 upkeep PRs open (settings: cadence daily, backstop weekly, max 3) (D59, D73,
    Q110; Lauren's gardening).

Key interfaces

From the design's module layout: "code-tidying: dissolve-comments renamed remove-comments with
an audit action; one agent code-tidying:comment-reviewer; upkeep PRs." Settings: "Upkeep:
cadence daily, backstop weekly, max 3. Comment postures none / necessary (pipeline default) /
explanatory (interactive default); edit scope diff." Variation verdicts: "Model and effort per
spawn: contain now; pointers to upstream docs, /multi-agent:route role defaults (D102)."

Slices, filed when this phase starts: remove-comments, upkeep-cadence.

Done when

  • The remove-comments skill and the comment-reviewer agent exist, and dissolve-comments
    does not.
  • Every slice sub-issue is closed by a merged PR, each skill-body cut with before/after evals.

Out of scope

  • The spread detector (dropped, Q24).

Activity

  1. kyle-sexton
    added
    needs-humanHuman-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
  4. kyle-sexton
    added a parent issue on Oct 16, 2026
  5. kyle-sexton
    set
    Work status
    to
    needs-spec
    on Oct 16, 2026

  6. github-actions commented on Oct 16, 2026

    @github-actions
    github-actionsBot
    on Oct 16, 2026 – with GitHub Actions
    Contributor

    Proposed work class: work-class: structural
    Basis: automated intake triage; the lanes App applied this class.

    Size: Large
    Complexity: Medium
    Uncertainty: Known
    Flags: none
    Blocked by: #7571

    Understood: rename dissolve-comments to remove-comments with an audit action, add the single code-tidying:comment-reviewer agent under posture settings, and set up the daily upkeep batch of at most 3 PRs. The issue lists its decisions and its done-when items, so I found no open intent question. The work spans two slices (remove-comments, upkeep-cadence), so it needs splitting. The body says it depends on #7571 (settings resolution), and I couldn't confirm that issue's state. I found no likely duplicates.

    Automated triage, applied by the lanes App.

  7. github-actions
    added
    needs-triageNot 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.
    and removed
    needs-triageNot 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
  10. kyle-sexton
    unmarked this as blocked on Oct 18, 2026

  11. kyle-sexton commented on Oct 20, 2026

    @kyle-sexton
    kyle-sexton
    on Oct 20, 2026
    MemberAuthor

    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.

  12. kyle-sexton
    removed
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Oct 24, 2026

  13. kyle-sexton commented on Oct 24, 2026

    @kyle-sexton
    kyle-sexton
    on Oct 24, 2026
    MemberAuthor

    Released for re-triage under the owner's 2026-10-24 rule: an issue stops for a person only for an intent or vision question, a security call, a host or attended run, or spend outside prepaid credit. The hold label came off and intake triage runs again now; it re-applies a hold, with a numbered question, when one of those applies.

    To hold this issue again, add needs-human (or status: needs-decision) and say why in a comment.

  14. github-actions
    added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    priority: mediumReal value, no hard deadline; normal backlog flow.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Oct 24, 2026
  15. melodic-automation-lanes
    added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    work-class: structuralRefactors, migrations, contract changes; cross-cutting and hard to reverse.
    on Oct 24, 2026
  16. melodic-automation-lanes
    marked this as blocked on Oct 24, 2026
  17. melodic-automation-lanes
    added
    status: needs-decisionAwaiting a human or maintainer judgment call.
    and removed
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Oct 24, 2026

  18. melodic-automation-lanes commented on Oct 24, 2026

    @melodic-automation-lanes
    melodic-automation-lanesBot
    on Oct 24, 2026
    Contributor

    Not admitted to the issue lane yet: Size large: the split into sub-issues at intake is pending (owner Q93).

  19. melodic-automation-lanes commented on Oct 24, 2026

    @melodic-automation-lanes
    melodic-automation-lanesBot
    on Oct 24, 2026
    Contributor

    The latest triage verdict holds nothing: the issue is at status: ready.

  20. kyle-sexton
    removed
    status: needs-decisionAwaiting a human or maintainer judgment call.
    on Oct 26, 2026

  21. kyle-sexton commented on Oct 26, 2026

    @kyle-sexton
    kyle-sexton
    on Oct 26, 2026
    MemberAuthor

    Released for re-triage under the owner's 2026-10-24 rule: an issue stops for a person only for an intent or vision question, a security call, a host or attended run, or spend outside prepaid credit. The hold label came off and intake triage runs again now; it re-applies a hold, with a numbered question, when one of those applies.

    To hold this issue again, add needs-human (or status: needs-decision) and say why in a comment.

  22. melodic-automation-lanes
    added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-specNeeds a Brief or plan before anyone can build it.priority: mediumReal value, no hard deadline; normal backlog flow.status: readyTriaged, unblocked, and fully specified; eligible to pick up.work-class: structuralRefactors, migrations, contract changes; cross-cutting and hard to reverse.

    Type

    Feature

    Fields

    Work status

    needs-spec

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions