diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a0e84c..137b0b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project are documented in this file. ## Unreleased +### Changed + +- Add advisory test-surface cues to weak verification theater: authoring questions and junk-pattern evidence for tests in an authorized change or an explicit simplicity review, without a new skill, deletion mandate, or coverage target. + ## 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. diff --git a/skills/efficiency/SKILL.md b/skills/efficiency/SKILL.md index 0666c56..db8d079 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. 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 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. When tests are in scope for that review or for authorized edits, use the test-surface cues in the same reference. 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 37bb5fd..82e8830 100644 --- a/skills/efficiency/references/design-and-code-simplicity.md +++ b/skills/efficiency/references/design-and-code-simplicity.md @@ -37,7 +37,7 @@ During an explicit simplicity review or when the quick ladder identifies materia 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. **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. When tests are in scope, apply the test-surface cues. 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. @@ -53,3 +53,28 @@ When a comment claims an invariant or required constraint, consider whether a ty When a comment is flagged, distinguish a redundant comment from a symptom of unclear code. During an authorized change, remove only the former directly. For the latter, recommend or, when authorized, apply the smallest in-scope root-cause clarification; retain any rationale the code still cannot express. Do not repeat the challenge recursively, enforce this vocabulary over the project's terms, equate fewer lines with better design, or manufacture a finding. Report a candidate rather than implementing it when behavior preservation is uncertain or the alternative expands the approved scope. + +### Test surface + +When an authorized change adds or changes tests, or an explicit simplicity review includes tests, use the questions and cues below. They are evidence cues. A review reports a concrete location and a safer in-scope alternative. This subsection does not authorize creating, running, or deleting tests outside the approved scope. + +Before adding or changing a test, answer four questions. A missing answer means do not add that test yet: + +1. What observable behavior, invariant, or independent contract does it protect? +2. What credible regression makes it fail? +3. Why does existing coverage not already catch that failure? Prefer one primary owner at the strongest boundary. Another layer needs its own distinct risk. Prefer extending a table-driven case or shared fixture over a near-duplicate. +4. Does it need a production seam (export, flag, wrapper, or injection hook) that no production caller needs? If it does, move the test to the real boundary instead. + +These patterns are evidence cues. A match still needs a concrete location; the pattern alone does not prove the test should be removed: + +- assertion-free coverage probes +- self-comparisons and identity copies +- exact source, import, or string searches of the implementation +- private predicate or call-shape tests duplicated at a real boundary +- duplicate invocations of the same contract across layers without a distinct risk +- tests whose only purpose is preserving test-only exports, globals, or wrappers +- expected values produced by the helper or renderer under test +- mocks that implement the asserted behavior +- negative controls that pass for an unrelated reason + +Optimize for confidence, not for how many tests are removed. A new test that must change under behavior-preserving refactoring is suspect; rewrite it at the owning boundary before adding it. An existing test with that shape is not automatically removable. Recommend removal only with evidence of redundancy or no contract value, and prefer improving a weak test so it observes the contract it was meant to protect.