jared/cc-os

Watch

Fork 0

Sweep the class comments that Style/Documentation forced #799

New issue

Closed

opened 2026-09-28 16:30:08 +00:00 by jared · 2 comments

jared commented

2026-09-28 16:30:08 +00:00

Owner

Sweep the class comments that Style/Documentation forced [capture]

Problem

The rubocop cop Style/Documentation demanded a comment above each class and module. The repo comment rule in CLAUDE.md forbids a comment unless removing it would make a maintainer clean up necessary behavior. Ticket #620 disabled the cop because it was the defect, not the agents who wrote the comments it forced. 49 files under plugins//lib and plugins//tests still carry a comment line immediately above a class or module line, placed there only to satisfy the now-disabled cop.

Observed

find plugins/*/lib plugins/*/tests -name "*.rb" | xargs awk -f count_class_comments.awk

49 files with a comment line directly preceding a class or module line

Reproduce

n/a: sweep task, not a bug reproduction

Approach

Required work:

For each of the 49 files, read the comment above the class/module line and decide: delete it if it only restates the code, keep it if it states an external constraint or rationale — check: rubocop --only Style/Documentation plugins/ still reports 0 offenses after the sweep (cop stays disabled)
Do not delete a comment that already meets the repo comment rule (external constraint or rationale) even if the cop originally forced it

Rejected: bulk-delete every flagged comment without reading it — some may state a real constraint and meet the repo comment rule already.

Acceptance criteria

Given the 49 files identified by ticket #620's sweep, when each is reviewed, then any comment above a class/module line that only restates the class/module name or purpose is deleted.
Given a comment above a class/module line that states an external constraint or rationale, when reviewed, then it is kept unchanged.

Owner sketch

n/a: prose sweep across existing files, no new object.

Origin

Trigger: ticket #620 (disable Style/Documentation), step 5 comment count
Improvised this session: none
Chain: 49 stale class-comments ← Style/Documentation cop forced them ← cop conflicted with the repo comment rule (DESIGN: CLAUDE.md comment rule)
Root candidate: this ticket
Where: plugins/os, plugins/os-sdlc, plugins/os-adr, plugins/os-aidd-lint, plugins/os-backlog
Session: 80ad7dfb-adda-49df-ac21-4afd6ead90ca
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/80ad7dfb-adda-49df-ac21-4afd6ead90ca.jsonl

# Sweep the class comments that Style/Documentation forced [capture] ## Problem The rubocop cop Style/Documentation demanded a comment above each class and module. The repo comment rule in CLAUDE.md forbids a comment unless removing it would make a maintainer clean up necessary behavior. Ticket #620 disabled the cop because it was the defect, not the agents who wrote the comments it forced. 49 files under plugins/*/lib and plugins/*/tests still carry a comment line immediately above a class or module line, placed there only to satisfy the now-disabled cop. ## Observed ``` find plugins/*/lib plugins/*/tests -name "*.rb" | xargs awk -f count_class_comments.awk ``` ``` 49 files with a comment line directly preceding a class or module line ``` ## Reproduce n/a: sweep task, not a bug reproduction ## Approach Required work: 1. For each of the 49 files, read the comment above the class/module line and decide: delete it if it only restates the code, keep it if it states an external constraint or rationale — check: `rubocop --only Style/Documentation plugins/` still reports 0 offenses after the sweep (cop stays disabled) 2. Do not delete a comment that already meets the repo comment rule (external constraint or rationale) even if the cop originally forced it Rejected: bulk-delete every flagged comment without reading it — some may state a real constraint and meet the repo comment rule already. ## Acceptance criteria 1. Given the 49 files identified by ticket #620's sweep, when each is reviewed, then any comment above a class/module line that only restates the class/module name or purpose is deleted. 2. Given a comment above a class/module line that states an external constraint or rationale, when reviewed, then it is kept unchanged. ## Owner sketch n/a: prose sweep across existing files, no new object. ## Origin - Trigger: ticket #620 (disable Style/Documentation), step 5 comment count - Improvised this session: none - Chain: 49 stale class-comments ← Style/Documentation cop forced them ← cop conflicted with the repo comment rule (DESIGN: CLAUDE.md comment rule) - Root candidate: this ticket - Where: plugins/os, plugins/os-sdlc, plugins/os-adr, plugins/os-aidd-lint, plugins/os-backlog - Session: 80ad7dfb-adda-49df-ac21-4afd6ead90ca - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/80ad7dfb-adda-49df-ac21-4afd6ead90ca.jsonl

jared added the

labels

2026-09-28 16:30:08 +00:00

jared referenced this issue

2026-09-28 16:30:12 +00:00

contract-auditor: treat a lint-mandated class comment as an external constraint and reconcile refactorer evidence before re-raising an item #620

jared commented

2026-09-28 16:53:57 +00:00

Author

Owner

Work started on branch ticket-799, 2026-09-28.

jared commented

2026-09-28 17:04:38 +00:00

Author

Owner

Resolution

Done: Deleted 47 class/module comments that only restated the class purpose across os, os-adr, os-aidd-lint, plus one stale rubocop:disable Style/Documentation directive. Kept 6 comments stating external tool quirks or constraints (hard_wrap.rb ADR-0058, issue_show.rb tea 0.13.0, project_shell.rb Bundler ENV, os-sdlc test_helper.rb x3).

Evidence: main e9632d87 (fast-forward from ticket-799). rubocop on the 47 changed files: no offenses. bin/test: 9 suites passed; one known LSP-daemon flake in os-sdlc reproduced on main and passed on rerun.

Follow-ups: none

## Resolution **Done:** Deleted 47 class/module comments that only restated the class purpose across os, os-adr, os-aidd-lint, plus one stale rubocop:disable Style/Documentation directive. Kept 6 comments stating external tool quirks or constraints (hard_wrap.rb ADR-0058, issue_show.rb tea 0.13.0, project_shell.rb Bundler ENV, os-sdlc test_helper.rb x3). **Evidence:** main e9632d87 (fast-forward from ticket-799). rubocop on the 47 changed files: no offenses. bin/test: 9 suites passed; one known LSP-daemon flake in os-sdlc reproduced on main and passed on rerun. **Follow-ups:** none

jared closed this issue

2026-09-28 17:04:39 +00:00

jared referenced this issue from a commit

2026-09-28 19:36:44 +00:00

chore(plugins): delete class comments forced by Style/Documentation (#799)