os-sdlc reviewer-guidance proposal: Write reviewer guidance on near-duplicate sibling classes #212

New issue

Open

opened 2026-08-01 15:47:50 +00:00 by jared · 2 comments

jared commented

2026-08-01 15:47:50 +00:00

Owner

This is a judgment-tier reviewer-prompt rule, NOT a RuboCop cop — the offense is cross-file/aggregate
in scope, which RuboCop's single-file cops cannot see.

Problem: /home/jared/dev/ruby-gems/caldotcom-api/lib/caldotcom/resources/routing_forms.rb and
.../routing_forms_scoped.rb are two classes differing only in mount point; likewise
bookings.rb / scoped_bookings.rb. scoped_bookings.rb:5-8 even documents the smell in a comment:
"reusing Resources::Bookings wholesale would expose methods that 404, so this is a separate class."
The Scope value object exists precisely so one parameterized class could serve both mounts.

Detection: Judgment-tier — reviewer guidance, not a cop. The offense is cross-file structural
similarity between two class bodies; RuboCop cops are single-file scoped (confirmed: even
Sdlc/Dry/DuplicatedStatementSequence only compares statement windows across defs inside one
file). Deciding whether the delta is a real capability difference or duplicated ceremony requires
reading the upstream API contract.

Solution: Reviewer prompt rule: "When two classes in the same directory share a name stem
(Foo / ScopedFoo / FooScoped), require the author to justify why a single class parameterized
by its collaborator (mount, scope, adapter) is insufficient."

Depends on: none

Note (exclusion check performed during decomposition): Sdlc/Dry/DuplicatedStatementSequence is
within-file, across-def statement windows (on_new_investigation → collect_defs(processed_source.ast)),
so it does NOT reach this cross-file near-duplicate class pair. This finding is genuinely novel but
judgment-tier, not mechanically detectable.

Discoverer: ruby-gems/caldotcom-api, session id unavailable, 2026-08-01. Filed during os-sdlc lint-mining of the api-wrapper skill output; ticket belongs on cc-os's tracker per cross-project filing.

Context: Discovered during architectural review of caldotcom-api (generated by the api-wrapper skill) vs hand-written shortpixel gem, 2026-08-01. Generality-tested against both repos. Pending validation via os-sdlc check before implementation. This is a judgment-tier reviewer-prompt rule, NOT a RuboCop cop — the offense is cross-file/aggregate in scope, which RuboCop's single-file cops cannot see. **Problem:** `/home/jared/dev/ruby-gems/caldotcom-api/lib/caldotcom/resources/routing_forms.rb` and `.../routing_forms_scoped.rb` are two classes differing only in mount point; likewise `bookings.rb` / `scoped_bookings.rb`. `scoped_bookings.rb:5-8` even documents the smell in a comment: `"reusing Resources::Bookings wholesale would expose methods that 404, so this is a separate class."` The `Scope` value object exists precisely so one parameterized class could serve both mounts. **Detection:** **Judgment-tier — reviewer guidance, not a cop.** The offense is cross-file structural similarity between two class bodies; RuboCop cops are single-file scoped (confirmed: even `Sdlc/Dry/DuplicatedStatementSequence` only compares statement windows across `def`s inside one file). Deciding whether the delta is a real capability difference or duplicated ceremony requires reading the upstream API contract. **Solution:** Reviewer prompt rule: "When two classes in the same directory share a name stem (`Foo` / `ScopedFoo` / `FooScoped`), require the author to justify why a single class parameterized by its collaborator (mount, scope, adapter) is insufficient." **Depends on:** none Note (exclusion check performed during decomposition): `Sdlc/Dry/DuplicatedStatementSequence` is within-file, across-`def` statement windows (`on_new_investigation` → `collect_defs(processed_source.ast)`), so it does NOT reach this cross-file near-duplicate class pair. This finding is genuinely novel but judgment-tier, not mechanically detectable. -------- **Discoverer:** ruby-gems/caldotcom-api, session id unavailable, 2026-08-01. Filed during os-sdlc lint-mining of the api-wrapper skill output; ticket belongs on cc-os's tracker per cross-project filing.

jared added the

labels

2026-08-01 16:36:51 +00:00

jared commented

2026-08-01 20:47:52 +00:00

Author

Owner

Deferred per ADR-0044: provenance is api-wrapper skill output (caldotcom/shortpixel gems), not an os-sdlc pipeline run — no reviewer has approved a sibling near-duplicate pair. Also likely unactionable: reviewer sees one ticket's diff; sibling classes arrive across tickets. Re-open trigger: an os-sdlc run ships an approved Foo/ScopedFoo pair.

jared added the

plugin/os-sdlc

worklist/lint-rule

labels

2026-08-13 18:15:50 +00:00

jared added the

frozen

label

2026-08-16 14:25:09 +00:00

jared commented

2026-08-16 14:26:07 +00:00

Author