From cac470445b2b225f42751a70017dce27d58186ac Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 30 Jun 2026 09:58:26 +0100 Subject: [PATCH] feat(review): add an always-on Fowler smell baseline to the Standards axis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Folds Refactoring ch.3 "Bad Smells in Code" into the in-progress `review` skill. The skill stays two-axis: smells layer into the Standards axis as a fixed, always-on baseline alongside a repo's documented standards, rather than a third axis. Because the baseline is needed on every run it lives inline in SKILL.md. Each smell is one line — its name carries the definition (the names are strong leading words) plus a diff-specific cue. Curated to ~12 high-signal smells; vague ones (Comments, Loops) and tooling-caught ones (Long Parameter List) are deliberately dropped. Two rules bind the baseline: a documented repo standard always overrides it, and every smell is reported as a judgement call, never a hard violation. The Standards sub-agent prompt now carries the baseline and these rules. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/in-progress/review/SKILL.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/skills/in-progress/review/SKILL.md b/skills/in-progress/review/SKILL.md index 63e71f3..77fd2bb 100644 --- a/skills/in-progress/review/SKILL.md +++ b/skills/in-progress/review/SKILL.md @@ -35,6 +35,26 @@ Look for the originating spec, in this order: Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`. +On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it: + +- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell. +- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces. + +Each name carries its own definition; match it against the diff: + +- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. +- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. +- **Feature Envy** — a method that reaches into another object's data more than its own. +- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). +- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. +- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. +- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. +- **Divergent Change** — one file or module is edited for several unrelated reasons. +- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. +- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. +- **Middle Man** — a class or function that mostly just delegates onward. +- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. + ### 4. Spawn both sub-agents in parallel Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both. @@ -42,8 +62,8 @@ Send a single message with two `Agent` tool calls. Use the `general-purpose` sub **Standards sub-agent prompt** — include: - The full diff command and commit list. -- The list of standards-source files you found in step 3. -- The brief: "Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." +- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it. +- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words." **Spec sub-agent prompt** — include: