From 44782a3a72480772193e4a2a0f0922e175ce297d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 24 Sep 2026 12:59:23 +0000 Subject: [PATCH] docs: add advisory generated-code smell signals Record five evidence cues for explicit simplicity reviews and bump the plugin patch version to 3.4.2. Co-authored-by: Dennis Geldmacher --- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- CHANGELOG.md | 4 ++++ docs/installation.md | 4 ++-- docs/usage.md | 2 ++ package-lock.json | 4 ++-- package.json | 2 +- plugin.json | 2 +- skills/efficiency/SKILL.md | 2 +- .../references/design-and-code-simplicity.md | 11 +++++++++++ 10 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index febfbac..c05b2e5 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "geldmacher-efficiency", - "version": "3.4.1", + "version": "3.4.2", "description": "Helps coding agents choose simpler solutions, keep context lean, and communicate clearly. For Cursor and Codex.", "author": { "name": "Dennis Geldmacher", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 921b8c4..33d01f4 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "geldmacher-efficiency", "displayName": "Efficiency", "description": "Helps coding agents choose simpler solutions, keep context lean, and communicate clearly. For Cursor and Codex.", - "version": "3.4.1", + "version": "3.4.2", "author": { "name": "Dennis Geldmacher", "email": "geldmacher.dennis@outlook.de" diff --git a/CHANGELOG.md b/CHANGELOG.md index f6b1631..9a0e84c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project are documented in this file. ## Unreleased +## 3.4.2 + +- Add advisory generated-code smell signals to explicit design and code simplicity reviews. They cover branching load, file cohesion, dead or redundant surface, type and error escape hatches, and weak verification theater, and stay evidence cues without numeric gates or extra tools. + ## 3.4.1 - Consolidate installation, usage, development, and recovery documentation; remove the redundant migration guide from plugin packages. diff --git a/docs/installation.md b/docs/installation.md index fc0568f..ecfc198 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -191,7 +191,7 @@ Each Efficiency GitHub Release contains separate packages for Cursor and Codex. On macOS or Linux, replace the example version and host when necessary, then verify exactly the two downloaded files that are covered by `SHA256SUMS`: ```sh -archive="geldmacher-efficiency-cursor-v3.4.1.zip" +archive="geldmacher-efficiency-cursor-v3.4.2.zip" verify_release_file() { file="$1" @@ -213,7 +213,7 @@ verify_release_file "provenance.json" || exit 1 On Windows PowerShell, the equivalent check selects the exact two entries before comparing their hashes: ```powershell -$archive = "geldmacher-efficiency-cursor-v3.4.1.zip" +$archive = "geldmacher-efficiency-cursor-v3.4.2.zip" $files = @($archive, "provenance.json") $checksumLines = Get-Content -LiteralPath .\SHA256SUMS diff --git a/docs/usage.md b/docs/usage.md index 2b3981a..55727d5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -44,6 +44,8 @@ You get a recommendation tied to the requirement and the code: what adds unneces **Example:** A change adds a configurable formatter registry for one date format. The project already has a date helper. A useful recommendation is to reuse the helper after checking timezone and invalid-input behavior. An adapter that hides necessary transaction recovery may still be worth keeping, even if it has only one implementation. +**Example:** A large new TypeScript module adds several `any` casts, an empty `catch`, and two near-identical helpers. A useful recommendation is to narrow the types, surface the error, and keep one helper — without demanding a coverage or mutation score the project does not already enforce. + These are illustrative examples, not recorded agent results or benchmarks. A review leaves files unchanged. To request an implementation, name the change and its scope: diff --git a/package-lock.json b/package-lock.json index d868ab8..b98634f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "geldmacher-efficiency-plugin-development", - "version": "3.4.1", + "version": "3.4.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "geldmacher-efficiency-plugin-development", - "version": "3.4.1", + "version": "3.4.2", "devDependencies": { "ajv": "^8.17.1", "ajv-formats": "^3.0.1", diff --git a/package.json b/package.json index 07b10f0..fea768a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "geldmacher-efficiency-plugin-development", - "version": "3.4.1", + "version": "3.4.2", "private": true, "description": "Development validation for the Geldmacher Efficiency Agent Plugins, Cursor, and Codex targets.", "engines": { diff --git a/plugin.json b/plugin.json index 741e3ef..7f77fd2 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "geldmacher-efficiency", - "version": "3.4.1", + "version": "3.4.2", "description": "Helps coding agents choose simpler solutions, keep context lean, and communicate clearly. For Cursor and Codex.", "author": { "name": "Dennis Geldmacher", diff --git a/skills/efficiency/SKILL.md b/skills/efficiency/SKILL.md index 9580b8e..0666c56 100644 --- a/skills/efficiency/SKILL.md +++ b/skills/efficiency/SKILL.md @@ -23,7 +23,7 @@ When RTK history, `rtk gain`, or filtered output informs an efficiency assessmen Report low value only for a concrete item whose removal or reduction improves the result, a decision, or necessary verification. Explain the evidence and alternative. Length, tone, or an AI-written appearance alone are not findings; preserve material evidence and uncertainty. -For coding, refactoring, or technical design work, read [design and code simplicity](references/design-and-code-simplicity.md) and apply its quick Evidence-Guided Simplicity ladder inside the user's stated objective and approved scope. Run its full bounded challenge only when the user explicitly requests a simplicity challenge, review, or simplification, or when the quick pass identifies a material complexity risk. Apply the quick ladder silently unless it changes the chosen solution, scope, or risk, or the user asks for the reasoning. +For coding, refactoring, or technical design work, read [design and code simplicity](references/design-and-code-simplicity.md) and apply its quick Evidence-Guided Simplicity ladder inside the user's stated objective and approved scope. Run its full bounded challenge only when the user explicitly requests a simplicity challenge, review, or simplification, or when the quick pass identifies a material complexity risk. Apply the quick ladder silently unless it changes the chosen solution, scope, or risk, or the user asks for the reasoning. On an explicit review, also apply the generated-code smell signals in that reference when the change looks agent-generated or unusually large for the requirement. Keep them advisory and scoped. For design simplicity, use the explicitly supplied design or proposal as the scope. For code simplicity, use an explicitly named scope first. Otherwise inspect the current Git change set: staged changes, unstaged changes, and untracked files reported by Git. If no changes exist or the project is not a Git repository, ask one focused question for the scope instead of expanding to the whole repository. Read nearby definitions, utilities, and conventions only when needed to assess the scoped code; keep findings and edits inside the approved scope. diff --git a/skills/efficiency/references/design-and-code-simplicity.md b/skills/efficiency/references/design-and-code-simplicity.md index d91941e..37bb5fd 100644 --- a/skills/efficiency/references/design-and-code-simplicity.md +++ b/skills/efficiency/references/design-and-code-simplicity.md @@ -28,6 +28,17 @@ Run the full challenge only when the user explicitly requests a simplicity chall 2. Inspect whether complexity is local or repeatedly exposed to callers and maintainers. Assess reader load on two independent axes: the layers someone must trace between a question and its answer, and the hidden or mutable state they must hold in mind. Include everything a caller must know: ordering, invariants, errors, configuration, and performance as well as signatures. Prefer project vocabulary and existing utilities over a new generic design language. 3. Treat a seam or abstraction as justified only when current evidence shows real variation or meaningful behavior behind it. Use the deletion test: if removing it makes complexity disappear, it is likely an unnecessary pass-through; if complexity spreads into callers, it may be earning its place. 4. Before adding a new abstraction or guard, look for demonstrably dead paths, duplicated decisions or validation, empty stubs, and speculative protection that the current requirements do not need. Remove an item only when the supplied scope proves that behavior and every affected caller remain safe. + +### Generated-code smell signals + +During an explicit simplicity review or when the quick ladder identifies material complexity risk, also scan the approved scope for these signals. Treat them as evidence cues, not numeric gates. Report a finding only with a concrete location and a safer in-scope alternative; do not invent thresholds or run specialized metric tools unless the project already exposes them. + +1. **Branching load:** nested conditionals, large switch/if cascades, or many early exits that force a reader to hold several paths at once. Prefer extracting the shared decision or collapsing dead branches over counting cyclomatic or cognitive complexity scores. +2. **File cohesion:** a file that mixes unrelated responsibilities or keeps growing around one hotspot. Prefer splitting by responsibility or moving helpers next to their callers. Do not treat a line-count ceiling as a simplicity target. +3. **Dead or redundant surface:** unused exports, empty stubs, copy-pasted blocks with renamed identifiers, pass-through wrappers that add no behavior. Remove only when every in-scope caller and required public surface stay safe. +4. **Type and error escape hatches:** new `any` / unbounded `unknown`, empty `catch`, or log-and-continue that hides failures. Prefer a precise type, a narrowed unknown, or an explicit error path at the trust boundary. +5. **Weak verification theater:** tests that mirror implementation structure, assert only mocks, or add coverage without a caller-visible contract. Prefer one check that would fail on a real defect over more lines of coverage. Do not recommend 100% coverage, mutation score zero, CRAP, or Halstead metrics unless the repository already uses those tools and the risk warrants them. + 5. Compare the current design with only the smallest viable alternative. State the difference in observable behavior, risk, validation effort, locality, reader load, and interface burden. 6. Prefer the alternative only when it materially reduces independent concepts without weakening correctness, security, performance, lifecycle semantics, domain distinctions, or project conventions. Otherwise conclude that the current design is already proportionate and explain why.