Skip to content

feat(review): always raise change amplification as an important finding - #16051

Merged
kyle-sexton merged 2 commits into
mainfrom
feat/review-change-amplification
Nov 14, 2026
Merged

kyle-sexton merged 2 commits into
mainfrom
feat/review-change-amplification

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: owner-decided change to the bundled code-design review criteria.

Summary

Code review now always raises change amplification (one logical change that had to edit several sites in step, in code or Markdown) as an IMPORTANT finding, and /planning:plan flags it at plan time.

Fix

  • plugins/review/skills/quality-gate/context/code-design.md: the Shotgun Surgery row becomes "Change amplification", IMPORTANT on every surface and quality bar, never CRITICAL, with no file-count threshold. It used to be a SUGGESTION raised only when the diff added to an existing set of coordinated edits. A new subsection says what the evidence is (the file and line of every site), what is not a site (a declared registry entry, a generated file, a rename or move, per-layer representation of one change), and that a fix too large for the change becomes a /coupling:reduce follow-up.
  • plugins/review/agents/code-reviewer.md: rates Shotgun Surgery by that row, as it already rates Duplicated Code by its row.
  • code-reviewer-duplicated-code-severity eval: the Shotgun Surgery case now expects IMPORTANT and never CRITICAL.
  • plugins/planning/skills/plan/SKILL.md: "Files affected" flags one logical change spread over many sites and proposes moving the repeated knowledge behind one module first, or records why not.

Verification

  • Every sample of the changed eval graders sorts as labeled (checked with a script against each grader's regex); validate-cases.py and check-matchers.py report no new failures.
  • markdownlint-cli2 on the changed Markdown: 0 issues.
  • The pre-push affected checks passed on the pushed head.
  • Left out: the eval suite was not run against a model (claude plugin eval); CI's lanes cover the repository's suites.

Related

  • plugins/planning/reference/design-principles.md "Deep modules and change amplification" is the design-time definition the plan step points at.
  • plugins/coupling/skills/reduce/reference/coupling-model.md already treats per-layer plumbing as not Shotgun Surgery; the criterion follows it.

🤖 Generated with Claude Code

kyle-sexton and others added 2 commits November 13, 2026 18:43
The code-design criteria and the code-reviewer agent rate change
amplification (Shotgun Surgery) IMPORTANT on every surface, never
CRITICAL, with every site the one change had to edit as evidence and a
/coupling:reduce follow-up when the fix is too large for the change.
/planning:plan flags the same shape in its files-affected list. The
code-reviewer severity eval now expects IMPORTANT for the PayPal sites.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…on sites

The coupling model already says an entity, its DTO and its mapper for
one new field are necessary plumbing, so the review criterion does not
count them as sites.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 13, 2026 23:45
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T23:47:41.346429Z 1ceaae3 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 1ceaae34f111754c16409f44c8ef80d3adb2929c: read 9 of 9 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16051

I read all 9 changed files in full, plus the two deleted eval files. I found no security issues.

What the change does. It edits prose review criteria and eval data:

  • code-design.md turns the Shotgun Surgery row into "Change amplification", rated IMPORTANT, and adds a new subsection for it.
  • code-reviewer.md now rates Shotgun Surgery by that row.
  • /planning:plan gets a "Files affected" sentence that flags one change spread over many sites.
  • The code-reviewer-duplicated-code-severity eval swaps its SUGGESTION grader and samples for an IMPORTANT grader and samples.
  • Two changeset fragments are added.

Checks I ran:

  • Trusted paths: no changed file matches a TRUSTED PATHS glob. The changed eval is code-reviewer-*, not security-review-*.
  • Trust controls: the diff touches none: no trusted-actor list, token request or broker, kill switch, merge hold, .github/actions/ action, workflow or pr-pipeline.yaml.
  • Plugin manifests: the diff changes no plugin.json or marketplace.json, so there are no userConfig or manifest lines to report.
  • Instruction-surface lens: the diff narrows no standing instruction. It raises a review severity (Shotgun Surgery goes from SUGGESTION to IMPORTANT) and adds one guidance line to the plan step. The only removed text is the old SUGGESTION-tier grader and samples, which the IMPORTANT ones replace. No permission, deny rule, hook list or other protected-class rule is removed or softened, so I did not need the protected-class register.
  • Untrusted content: nothing new reaches a credentialed lane. The new grader is a static regex in eval data and the new samples are fixed strings.
  • PR context: no embedded instructions aimed at the review lane.

Prior findings: none; this lane has reviewed 0 earlier heads, so this was a full review, not blocking only.

critical-findings: 0

@github-actions

Copy link
Copy Markdown
Contributor

claude-review reviewed 1ceaae34f111754c16409f44c8ef80d3adb2929c: read 9 of 9 changed file(s); 0 finding(s), 0 as inline comments.

Code review: PR #16051, head 1ceaae34

No findings. This was a full first review, not limited to blocking findings. I read every hunk of all 9 listed files. I also read the two deleted files (graders/shotgun-surgery-not-blocking.md and samples/shotgun-surgery-not-blocking.json), which are not on the file list.

What the change does

  • code-design.md: the Shotgun Surgery row becomes Change amplification, rated IMPORTANT on every surface and at every quality bar. A new ### Change amplification subsection sets three things:
    • The finding is never CRITICAL.
    • Its evidence is the file and line of every site the change edited.
    • Registry entries, generated files, renames or moves, and per-layer representation are not sites.
  • The dispatch brief now names the new subsection and asks the reviewer to list every site.
  • code-reviewer.md: the "Repetition severity" rule now covers Shotgun Surgery as well, pointing at the new row and subsection.
  • Eval code-reviewer-duplicated-code-severity: the shotgun-surgery-not-blocking grader and its samples become shotgun-surgery-important, which expects IMPORTANT and fails on CRITICAL or SUGGESTION. The prompt's description and expected_outcome are updated to match.
  • planning/skills/plan/SKILL.md: "Files affected" now flags one logical change spread over many sites.

Consistency checks

  • Wording matches. The row, the subsection, the agent rule, the dispatch brief and both changelog fragments all say the same thing.

  • The eval still binds the rule. case.yaml lists no graders, so the renamed grader is picked up. Shotgun Surgery is in the shipped ## Baseline of plugins/review/reference/design-smells.md, so the agent's rule applies under the default smell_baseline.

  • The fixture is a real case. The scaffold's PayPal edit touches three per-method files that are not a declared registry, so it counts as change amplification under the new definition.

  • Grader regex. I traced the new grader against several samples by hand and they sort as labeled:

    • the negated "not CRITICAL" pass sample;
    • the CRITICAL-table fail sample;
    • the "CRITICAL section heading" fail sample.

    I did not run the regex. The author's script check of every sample is their claim and I have not verified it.

  • Planning link. The ../../reference/design-principles.md link in the planning skill resolves, and the "Deep modules and change amplification" entry exists at line 62.

  • No old wording left. No other eval or reference in the repository still expects Shotgun Surgery at SUGGESTION. The only other sample that mentions it, qg-code-design-sanctioned/samples/no-critical.json, is a registry case under a no-CRITICAL grader, and it is unaffected.

  • Repo standard has its own carve-out. docs/standards/design-for-change.md rule 2 excludes files a feature spans inside its own slice. Consumer criteria win over the bundled defaults, so that carve-out still governs this repository.

Closing issue

The PR closes no issue ("owner-decided change"), so there were no acceptance criteria to check.

Not verified

I did not run the eval suite against a model. The PR body says it was not run either.

Spend

The broader IMPORTANT rating may lengthen review output a little. It draws only on prepaid model usage.

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 13, 2026
Merged via the queue into main with commit 09ccaba Nov 14, 2026
66 of 78 checks passed
@kyle-sexton
kyle-sexton deleted the feat/review-change-amplification branch November 14, 2026 00:01
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant