feat(review): add an always-on Fowler smell baseline to the Standards axis

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) <noreply@anthropic.com>
This commit is contained in:
Matt Pocock 2026-06-30 09:58:26 +01:00
parent 43ea0884b0
commit cac470445b

View file

@ -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`. 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 ### 4. Spawn both sub-agents in parallel
Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both. 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: **Standards sub-agent prompt** — include:
- The full diff command and commit list. - The full diff command and commit list.
- The list of standards-source files you found in step 3. - 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 — 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 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: **Spec sub-agent prompt** — include: