@lifeaitools/rdc-skills 0.34.1 → 0.35.0

package/skills/clean-code-analyzer/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: clean-code-analyzer
+description: >-
+  Usage `rdc:clean-code-analyzer <path> [--project-root <dir>]` — naming,
+  dead code, function-size, and error-handling smells outside SOLID's scope
+  (SOLID governs class/module shape; this governs whether the code inside is
+  readable and honest about what it does). N1/N2/N4/N7/F1/F2/E1/E2/G9 are
+  mechanical AST checks, not LLM judgment — see `scripts/clean-code-score.mjs`.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# clean-code-analyzer — Naming, Dead Code, Function Size, Error Handling
+
+## Scope — what this covers that solid-validator doesn't
+
+`solid-validator` scores the SHAPE of a class/module (cohesion, coupling,
+inheritance contracts). This skill covers what's INSIDE that shape: does a
+name lie about what it does, is there code nothing calls, is a function too
+big to hold in one head, is an error silently swallowed. Two different
+failure classes; a class can score perfectly on SOLID and still be unreadable.
+
+## Why 8 of these rules are mechanical, not a dispatched agent
+
+Same reasoning as `solid-validator`: a rule that names a real AST fact
+(a declared binding's name and length, a numeric literal's declaration
+context, a statement count, a parameter count, an empty catch block, an
+unreachable constant-conditional branch, a cross-file reference count) does
+not need LLM judgment to detect — it needs the same NormalizedUnit contract
+`lib/language-plugin.mjs` already defines, extended with the facts these
+rules read (`statementCount`, `declaredNames`, `magicNumbers`, `emptyCatches`,
+`deadConditionals` — see that file's JSDoc — plus the OPTIONAL
+`deadExportsOf(filePath, projectFilePaths)` plugin method for G9's
+cross-file half). All eight live in `scripts/lib/clean-code-scoring.mjs` as
+pure functions over a `NormalizedUnit`, exactly like `solid-scoring.mjs`.
+
+Detection logic (thresholds, patterns) is ported/adapted from
+architecture-toolkit's real implementation —
+github.com/OnSightTeam/architecture-toolkit (MIT),
+`src/agents/clean-code-analyzer/tools/{naming,function,code-smell}-validator.ts`
+— with per-rule citations in `clean-code-scoring.mjs`'s own comments. Their
+checks are whole-file text regexes with an occurrence-count threshold (e.g.
+"flag single-letter names only if more than 3 appear in the file", to
+suppress the regex's own false-positive rate); ours reads the real AST per
+declared binding, so context is known directly and every genuine occurrence
+is its own finding — no threshold needed. F1 (>20 statements) and F2 (>3
+params) independently corroborate architecture-toolkit's own real thresholds
+at `function-validator.ts:52` and `:82`.
+
+Dogfooded live against this repo's own `scripts/` tree (75 files): N1 fired
+271 times, N4 223 times, F1 53 times, E1 31 times, F2 10 times, G9 5 times
+(3 confirmed by independent repo-wide grep: `registeredPlugins`,
+`packageMetrics`, `cleanupStaleWorktrees` — genuinely zero callers). N7 fired
+0 times on real code (no `*Manager`/`*Handler`/`*Util` names in this repo) —
+confirmed against a constructed fixture instead. N2's low-confidence label is
+earned: it also produced one real false positive (`pm2`, a product name,
+matches the numeric-suffix heuristic) alongside real hits (`data`, `temp`,
+`val`) — report it as a heuristic finding, never a certainty.
+
+## Procedure
+
+1. **Run the mechanical scorer:**
+   ```bash
+   rdc-clean-code-score <path> [--project-root <dir>] [--no-dead-exports] --format json
+   ```
+   (installed globally via `npm link`/publish — see `package.json`'s
+   `bin.rdc-clean-code-score`; falls back to
+   `node <rdc-skills-install-path>/scripts/clean-code-score.mjs`.)
+
+2. **Read `results`** — per-unit findings for N1 (cryptic names), N2 (heuristic
+   meaningless-distinction names, low confidence), N4 (magic numbers), N7
+   (generic class/function names), F1 (>20 statements), F2 (>3 params), E1
+   (empty catch blocks), and G9 (dead code — BOTH halves: unreachable
+   constant-conditional branches, always measured, AND unused exports via a
+   real cross-file `findReferencesAsNodes()` reference-graph walk, measured
+   only when `deadExportsScope.positiveControlOk` is true).
+
+3. **Read `deadExportsScope`** before trusting ANY G9 unused-export finding.
+   `positiveControlOk: false` means the cross-file reference scan itself
+   failed a known-used-symbol control — G9's export-usage findings are
+   withheld entirely in that case (the unreachable-conditional half still
+   ran). An unverified "zero callers" is a guess, not a finding — see
+   `.claude/rules/prove-absence-positive-control.md`.
+
+4. **Naming-honesty judgment pass — this stays a dispatched agent, on
+   purpose.** N1/N2/N7 catch SHAPE (a name too short, too generic, or
+   suspiciously paired) — none of them can tell whether a name LIES about
+   behavior (a function named for its happy path that also has a side
+   effect, a boolean named affirmatively that is usually false, a variable
+   whose name predates a refactor and no longer matches its contents). That
+   needs reading intent against implementation, which is judgment:
+   ```
+   Agent({
+     subagent_type: "pr-review-toolkit:code-reviewer",
+     description: "clean-code naming-honesty pass",
+     prompt: "Review `git diff <ref>...HEAD` for names that misdescribe what
+              the code does — not too short or too generic (a mechanical
+              scorer already caught that), but SEMANTICALLY WRONG: a
+              happy-path name hiding a side effect, an affirmative boolean
+              that's usually false, a name that predates a refactor. High-
+              confidence findings only. Return CLEAN_CODE_NAMING_COMPLETE
+              with { findings: [{file:line, name, issue, suggested_name}] }."
+   })
+   ```
+
+5. **Report:**
+   ```
+   ## Clean Code Analysis
+   ### Mechanical findings (N1/N2/N4/N7/F1/F2/E1/G9) — rdc-clean-code-score
+   ### Dead-export scan status (positive control OK / withheld — reason)
+   ### Naming-honesty findings (dispatched judgment)
+   ### Not implemented (see below)
+   ## Verdict: CLEAN / HAS ISSUES
+   ```
+
+## Not implemented — named, not faked
+
+These stayed OUT of the mechanical catalog because a cheap regex/AST version
+would report a confident number for evidence that's actually a judgment call,
+which is worse than not measuring it. Route these through a dispatched
+`pr-review-toolkit:code-reviewer` pass reading the real diff, same shape as
+step 4, or accept they are genuinely unmeasured this round:
+
+| ID | Why it stays judgment |
+|----|------------------------|
+| N3 | Unpronounceability is a phonetic/readability judgment, not an AST fact — a consonant-run regex flags real acronyms and abbreviations as often as bad names. |
+| N5, N6 | Member-prefix (`m_`/`_`) and interface-`I`-prefix conventions are STYLE-GUIDE-dependent, not universal Clean Code violations — some house styles mandate them. Flagging them needs the repo's own convention as ground truth, which isn't in `NormalizedUnit`. |
+| C1–C5 | Comment quality/staleness needs comparing prose against code behavior over time — semantic, not structural. |
+| G5 | Duplication detection worth trusting needs real similarity (token/AST-diff) across the whole codebase, not a per-file line-repeat count — a per-unit, per-file scorer is the wrong shape for a cross-file structural-clone problem. |
+| G14 | "Feature Envy" (a member using another object's data more than its own) needs cross-class field-access comparison this scorer doesn't do — SRP's connected-component analysis in `solid-scoring.mjs` is the adjacent real check, not a substitute. |
+| G16, G28 | Nested-ternary / complex-boolean "obscures intent" is a readability judgment about a specific reader's tolerance, not a fixed threshold — a mechanical AST-depth count would either flag idiomatic short expressions or miss genuinely tangled ones depending on where the line is drawn. |
+
+## Rules
+
+- Dead-export (G9) claims MUST cite the positive control that proved the scan
+  itself works — `deadExportsScope.positiveControlOk` — an unverified "zero
+  callers" claim is not a finding, it's a guess with a command attached.
+- N2 findings are heuristic and low-confidence BY DESIGN — report them as
+  "worth a look," never as certain violations. A real false positive
+  (`pm2` flagged as a "numeric-suffix" name) was found during dogfooding and
+  is why this label is load-bearing, not decorative.
+- Do not flag a name as wrong without a suggested replacement — "confusing"
+  alone is not actionable.
+- Never claim a Not-Implemented rule (N3/N5/N6/C1-C5/G5/G14/G16/G28) was
+  checked — it wasn't, on purpose.

package/skills/package-design/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: package-design
+description: >-
+  Usage `rdc:package-design <path>` — module boundary and export-surface
+  review: does this package expose the right things, hide the right things,
+  and sit at the right size.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# package-design — Module Boundary & Export-Surface Review
+
+## Procedure
+
+1. **Read the package's barrel** (`src/index.ts`/`.mjs`) and list every
+   export. For each: is it used by anything OUTSIDE the package? An export
+   used only internally is an encapsulation leak — it should not be public.
+   Use the same call-graph approach as `clean-code-analyzer`'s dead-code
+   check, with the same positive-control requirement.
+
+2. **Check for a missing barrel** — internal files imported directly by
+   other packages (`import { x } from '../../foo/src/internal/thing.mjs'`
+   instead of `from '../../foo/src'`) is a boundary violation even when
+   nothing is technically broken; it means the package has no real public
+   contract, just whatever consumers happened to reach into.
+
+3. **Size check** — a package with one export and a package with sixty are
+   both worth asking about. Too small: does this need to be its own package,
+   or is it one file that belongs inside a consumer? Too large: does it
+   actually have one responsibility, or has "utils"/"shared"/"core" become
+   several unrelated things sharing a directory (the same LCOM-style
+   cohesion question `solid-validator`'s SRP score asks, applied at the
+   package level instead of the class level).
+
+4. **Dependency direction — mechanical, real numbers.** Run
+   `node scripts/package-metrics-cli.mjs <packagesRoot>` (root containing
+   `packages/*`, or `--dirs <d1,d2,...>` for an explicit set). This is a
+   REAL package-dependency graph, not a `package.json` `dependencies` read —
+   many real monorepos (rdc-harness among them) declare zero
+   `dependencies` and wire packages together entirely through relative
+   `../../pkg/src/...` imports, which `package.json` alone can't see. It
+   resolves every `import`/`export ... from`/`require()`/dynamic `import()`
+   across every sibling package (implementation: `scripts/lib/package-metrics.mjs`,
+   independent of the ts-morph `language-plugin.mjs` used by SRP/OCP/etc —
+   plain-text/regex parsing, so it works on any language whose imports look
+   like ES/CJS syntax) and reports, per package:
+
+   | Metric | Meaning | Formula |
+   |---|---|---|
+   | `ca` | how many OTHER packages import from this one | count of distinct importing packages |
+   | `ce` | how many OTHER packages this one imports from | count of distinct imported packages |
+   | `instability` (I) | Ce/(Ca+Ce); `null` if Ca+Ce=0 (isolated, no coupling data — not 0) | Martin's I |
+   | `abstractness` (A) | exported `interface`/`type` ÷ exported total (`class`/`function`/`const`/…); `null` unless the package contains at least one real `.ts`/`.tsx` file | Martin's A |
+   | `distanceFromMainSequence` (D) | how far off Martin's main sequence; `null` if either I or A is null | `\|A + I − 1\|` |
+   | `cycles` | REAL cycle paths through this package (e.g. `a -> b -> c -> a`), not just "a cycle exists" | ADP — Acyclic Dependencies Principle |
+   | `zone` | `main-sequence` (D≤0.5) / `zone-of-pain` (I<0.5, A<0.5) / `zone-of-uselessness` (I>0.5, A>0.5) / `off-main-sequence` / `unmeasurable` | |
+
+   **Honest limits, not fabricated numbers:** `abstractness` is `null` for a
+   plain `.mjs`/`.js` package — there is no type system to measure, and
+   reporting a fake 0 would silently claim "fully concrete" for a package
+   this tool has no basis to judge. Measurability is decided by file
+   EXTENSION (does the package contain a real `.ts`/`.tsx` file), never by
+   whether `interface`/`type` keywords happen to appear — a `.ts` package
+   with zero interfaces is a real, legitimate A=0, not "unmeasurable" (this
+   was a real bug, caught by a synthetic fixture during dogfooding, fixed
+   before ship). Declaration counting excludes test files — a test fixture
+   that embeds source-as-a-STRING (e.g. a template literal holding
+   `` `export interface Page {...}` `` as test input) is indistinguishable
+   from a real declaration to a regex scanner; `ca`/`ce` still count
+   test-file imports, since those are real coupling regardless.
+
+   Dogfooded against `rdc-harness/packages/*` (21 packages, zero `.ts`
+   files, zero `package.json` `dependencies` entries — everything wired via
+   relative imports): every `ca`/`ce` number was hand-verified against a
+   manual `grep -rn "from '\.\./\.\./"` cross-check across the whole tree,
+   with one instructive miss — a dynamic `await import('../../delivery/src/...')`
+   inside `adoption/test/isolation-and-adoption.test.mjs` that the naive
+   `grep ... from` positive control doesn't catch (no `from` keyword on a
+   dynamic import) but this tool correctly does. Zero ADP cycles found,
+   confirmed by hand against the full 22-package edge list. `abstractness`
+   was `null` for all 22 — correct, since the fleet has no TypeScript.
+
+5. **Dispatch judgment for what's not mechanical:**
+   ```
+   Agent({
+     subagent_type: "pr-review-toolkit:code-reviewer",
+     description: "package-design judgment pass",
+     prompt: "Review the package at <path>: does its actual responsibility
+              match its name and its README/CLAUDE.md description? Would a
+              new contributor guess what belongs here correctly? Return
+              PACKAGE_DESIGN_COMPLETE with
+              { findings: [{severity, issue, suggestion}] }."
+   })
+   ```
+
+6. **Report:**
+   ```
+   ## Package Design Review
+   | Export | Used externally? | Should be public? |
+   ### Boundary leaks (direct internal imports from outside)
+   ### Size/cohesion note
+   ### Dependency-direction — Ca/Ce/I/A/D/zone table (from package-metrics-cli.mjs), cycles called out by name
+   ## Verdict: CLEAN / HAS ISSUES
+   ```
+
+## Rules
+
+- An export-usage claim needs the same positive control as dead-code
+  detection — prove the scan works before trusting a zero result.
+- Do not recommend splitting or merging a package without naming the exact
+  target shape — "this is too big" alone is not actionable.
+- Ca/Ce/I/A/D/zone/cycles are MECHANICAL (step 4) — never eyeball or
+  estimate these from reading `package.json`/imports; run
+  `package-metrics-cli.mjs` and quote its numbers. A `zone-of-pain` or
+  `zone-of-uselessness` verdict, or any reported `cycles` entry, needs the
+  actual tool output in the report, not a paraphrase.

package/skills/pattern-advisor/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: pattern-advisor
+description: >-
+  Usage `rdc:pattern-advisor <path>` — suggests an applicable design pattern
+  for a given code shape. Factory Method/Builder/Singleton/Decorator/
+  Adapter/Facade/Strategy/Observer/Command/Template Method are mechanical
+  AST checks, not LLM judgment — see `scripts/pattern-score.mjs`. Advisory
+  only; never rewrites code itself.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# pattern-advisor — Design Pattern Suggestions
+
+## The failure this guards against
+
+A pattern applied because it's a pattern, not because the code needs it, is
+the same kind of theater as a test written to make a claim go green. This
+skill's first output for most inputs should be "no pattern needed" — that is
+a valid, common, correct answer, not a non-answer.
+
+## Why 9 of these are mechanical, not a dispatched agent
+
+Same reasoning as `solid-validator` and `clean-code-analyzer`: a rule that
+names a real, AST-visible structural shape (a switch statement's
+discriminant and case bodies, a constructor's parameter count, an
+if-block's calls, a call chain's depth, a static property's name) does not
+need LLM judgment to detect. All 9 live in `scripts/lib/pattern-scoring.mjs`
+as pure functions over a `NormalizedUnit` (same `lib/language-plugin.mjs`
+contract every other mechanical scorer in this repo shares), fed by facts
+computed once in `lib/plugins/typescript.mjs`.
+
+Detection heuristics (thresholds, word lists, structural shapes) are ported
+from architecture-toolkit's REAL implementation —
+[OnSightTeam/architecture-toolkit](https://github.com/OnSightTeam/architecture-toolkit)
+(MIT), `src/agents/pattern-advisor/tools/{creational,structural,behavioral}-
+pattern-analyzer.ts` — fetched from raw.githubusercontent.com and read in
+full, per-detector citations in `pattern-scoring.mjs`'s own comments. Their
+own checks are whole-file text regexes with zero scoping to which
+switch/if/call the signal actually came from (e.g. a type-switch's `new`
+check matches if "new" appears anywhere before the switch's closing brace,
+even in an unrelated statement three lines later). Ours walks the real AST
+per switch-case / if-block / call-expression, so every finding is
+attributable to the real member and — for the three patterns whose toolkit
+signal is inherently node-scoped (Factory Method's switch+new, Strategy's
+switch+behavior-call, Decorator's conditional-feature-call) — the real line
+it was found on.
+
+Confidence and priority numbers are the LITERAL values architecture-
+toolkit's own analyzers return, hard-coded per detector (not computed). The
+calibration table below (unchanged from before this scorer existed) was
+checked against every one of them: **no discrepancy found.**
+
+Dogfooded live (2026-08-20):
+- **This repo's own `scripts/` tree** (36 JS/TS files scanned, 8 non-JS
+  skipped and reported, not silently passed): Decorator fired 20 times,
+  Adapter 4, Facade 1, Observer 1, Template Method 1 — 12 files carried a
+  finding. **Factory Method, Builder, Singleton, Strategy, and Command all
+  scored ZERO on real code.** Per
+  `.claude/rules/prove-absence-positive-control.md`, a zero is not reported
+  as a finding until the scanner is proven to work: a constructed positive-
+  control fixture (a type-switch factory, a 6-param constructor, a
+  `getInstance()` singleton, a calculate/tax switch, and an undo/redo/
+  queue/execute command-history class) scored 2/1/1/1/1 findings
+  respectively across those same 5 detectors — the zero on real code is a
+  genuine absence, not a broken scanner.
+- **`rdc-harness/packages`** (a different, larger real corpus, 87 JS/TS
+  files scanned, 17 carried a finding): Factory Method fired once — a real Redux-style event reducer
+  switching on `type` and constructing via `new` (`core/src/events.mjs`,
+  `reduce()`) — Decorator once, Adapter 13 times (this package genuinely has
+  an `adapters.mjs` module), Facade twice, including a 19-call chain in
+  `transaction/src/index.mjs`'s `SaveTransaction##drive`.
+- **ATF-compatibility**: `--format json` run twice on each of the two
+  corpora above produced byte-identical output both times (`diff` empty) —
+  no timestamps, file paths relative to the scanned root, and every
+  results/finding array explicitly sorted.
+
+## Confidence calibration
+
+Adapted from the confidence values actually shipped in architecture-
+toolkit's `src/agents/pattern-advisor/tools/*.ts` — every detector there
+returns a confidence in exactly the 70-90 band, never higher, never lower —
+and now hard-coded verbatim in `pattern-scoring.mjs`:
+
+| Pattern | Confidence | Priority | Toolkit citation |
+|---|---|---|---|
+| Factory Method (switch-on-type + `new`) | 90% | high | `creational-pattern-analyzer.ts:43-53` |
+| Factory Method (scattered `new`, >5 total >3 unique) | 75% | medium | `creational-pattern-analyzer.ts:68-83` |
+| Builder (constructor >4 params) | 85% | high | `creational-pattern-analyzer.ts:98-108` |
+| Singleton (`private static instance` \| `getInstance()`) | 70% | medium | `creational-pattern-analyzer.ts:128-138` |
+| Strategy (switch + calculate/process/execute/validate/format) | 90% | high | `behavioral-pattern-analyzer.ts:44-54` |
+| Command (undo/redo/history/queue/execute, >4) | 80% | high | `behavioral-pattern-analyzer.ts:107-119` |
+| Observer (notify/update/inform/broadcast, >3) | 75% | medium | `behavioral-pattern-analyzer.ts:74-86` |
+| Adapter (convert/transform/adapt) | 80% | medium | `structural-pattern-analyzer.ts:74-84` |
+| Decorator (conditional wrap/add/extend/enhance) | 75% | medium | `structural-pattern-analyzer.ts:43-53` |
+| Facade (>5 `a.b.c(...)` calls) | 70% | medium | `structural-pattern-analyzer.ts:104-114` |
+| Template Method (>2 members call initialize/process/cleanup) | 70% | medium | `behavioral-pattern-analyzer.ts:139-150` |
+
+Never report a confidence outside 70-90% for a *heuristic* pattern match —
+below 70 the finding isn't worth surfacing; above 90 claims a certainty
+static analysis of a live codebase cannot honestly produce.
+
+## Procedure
+
+1. **Run the mechanical scorer:**
+   ```bash
+   rdc-pattern-score <path> --format json
+   ```
+   (installed globally via `npm link`/publish — see `package.json`'s
+   `bin.rdc-pattern-score`; falls back to
+   `node <rdc-skills-install-path>/scripts/pattern-score.mjs`.)
+
+2. **Read `results`** — per-file, per-unit, per-pattern findings. Each
+   finding carries `location` (unit#member[:line] where a line is known),
+   `problem` (the shape observed, named first — never lead with the
+   recommendation), `solution`, `reasoning`, `confidence`, `priority`,
+   `alternatives`, `tradeoffs: {pros, cons}`, and `source` (the exact
+   toolkit file:line it was ported from).
+
+3. **A file/unit with zero findings across all 9 patterns is "no pattern
+   needed" — report it as plainly as a positive recommendation.** It
+   carries no confidence/priority scoring (there is nothing being
+   recommended to score). This is the expected, common, correct answer for
+   most code — the dogfooding numbers above show 5 of 9 detectors scoring
+   zero on this repo's own real source.
+
+4. **Domain-fit judgment pass — this stays a dispatched agent, on
+   purpose.** The mechanical scorer can prove a shape exists (a type-switch
+   constructing via `new`, a 6-parameter constructor) but cannot judge
+   whether the recommended pattern is actually the RIGHT fit for THIS
+   domain, or merely structurally similar to one that would be — e.g. a
+   6-param constructor on a one-off internal test fixture that's called
+   exactly once is not a real Builder candidate even though it trips the
+   mechanical threshold; a type-switch in a state-machine reducer may be
+   the CORRECT idiom for that domain (Redux-shaped code), not a Factory
+   Method smell. That needs reading intent and call-site context against
+   structure, which is judgment:
+   ```
+   Agent({
+     subagent_type: "pr-review-toolkit:code-reviewer",
+     description: "pattern-advisor domain-fit pass",
+     prompt: "Given these mechanical pattern-advisor findings (paste the
+              JSON), judge for EACH finding whether the recommended pattern
+              is actually the right fit for this code's domain and call-site
+              context, or whether the shape is structurally similar but the
+              recommendation doesn't actually help here (a one-off fixture,
+              a legitimate domain idiom like a reducer's type-switch, a
+              constructor called from exactly one call site). Return
+              PATTERN_ADVISOR_DOMAIN_FIT_COMPLETE with
+              { findings: [{location, pattern, verdict: apply|skip, reason}] }."
+   })
+   ```
+
+5. **Every recommendation carries trade-offs — pros AND cons, never pros
+   alone** — the scorer's own `tradeoffs` field already supplies both; do
+   not drop the cons when reporting. **At least one alternative pattern is
+   named where the toolkit source names one** (`alternatives` field) — do
+   not invent a generic "or don't" alternative where the source gives none.
+
+6. **Report:**
+   ```
+   ## Pattern Advice
+   | File:Line | Shape observed | Recommendation | Confidence | Priority | Why now |
+   ### Trade-offs & alternative (per recommendation)
+   ### Domain-fit verdicts (dispatched judgment, step 4)
+   ### No pattern needed (files/units with zero mechanical findings)
+   ```
+
+## Rules
+
+- Never recommend a pattern without naming the shape it responds to
+  (`problem` field) — the mechanical scorer already does this; do not strip
+  it when reporting.
+- Never recommend a pattern without its confidence score, priority, both
+  pros AND cons, and its named alternative(s) if the toolkit source has any.
+- "No pattern needed" is a first-class, expected verdict — report it as
+  plainly as a positive recommendation.
+- A mechanical finding is a structural fact, not a final verdict — run the
+  domain-fit judgment pass (step 4) before telling Dave to actually apply a
+  recommendation; do not present a raw mechanical hit as settled advice.
+- Do not write the refactor here — hand off to
+  `pattern-refactoring-guide` for the concrete before/after.
+- A zero-finding pattern on a real scan is not reported as "clean" without
+  having proven the detector fires on a positive-control fixture first (see
+  the dogfooding section above) — same discipline as
+  `.claude/rules/prove-absence-positive-control.md`.
+
+## Not implemented — named, not faked
+
+Everything the toolkit's own 9 detectors check is now mechanical (see
+above). What's left is genuinely NOT a shape a regex or an AST walk can
+settle:
+
+| Question | Why it stays judgment |
+|----------|------------------------|
+| Is the recommended pattern actually the right fit for this domain, or just structurally similar? | Needs reading intent against call-site context — a type-switch in a reducer may be the correct domain idiom, not a smell; a 6-param constructor called once is not a real Builder candidate even though it trips the mechanical threshold. Routed through the domain-fit judgment pass (step 4). |
+| Would applying this pattern actually improve the code, given its growth trajectory? | "Small, stable branch count with no growth signal" is a trend judgment a single-snapshot AST scan cannot make — the mechanical scorer reports the shape at THIS commit; whether it is worth refactoring is a maintainer call. |
+
+## Worked Example — this repo's own dogfood run
+
+Real target, scanned in full during this scorer's build:
+[`C:/Dev/rdc-skills/scripts/lib/plugins/typescript.mjs`](file:///C:/Dev/rdc-skills/scripts/lib/plugins/typescript.mjs)
+— 4 real mechanical findings, real `rdc-pattern-score` output:
+
+```
+## Pattern Advice — scripts/lib/plugins/typescript.mjs
+| File:Line | Shape observed | Recommendation | Confidence | Priority | Why now |
+| unitsFromSourceFile:435 | if-block calls a function whose name matches
+  wrap/add/extend/enhance | Decorator | 75% | medium | Single structural
+  signal, no growth trend evidence in a snapshot scan — flagged, not settled. |
+| deadExportsOf:552 | same shape, different member | Decorator | 75% | medium | ditto |
+| referenceSitesOf:590 | same shape, different member | Decorator | 75% | medium | ditto |
+| (unit-wide) | 3 members each call an initialize/process/cleanup-named
+  function | Template Method | 70% | medium | Lowest band — pure keyword
+  frequency, no shared-"how" evidence beyond the name match. |
+
+### Domain-fit verdict (dispatched judgment)
+All 3 Decorator findings: SKIP — each if-block is a real conditional
+branch (class-vs-module dispatch, a missing-file guard, a found/not-found
+check), not feature decoration; the wrap/add/extend/enhance substring match
+is a false positive on ordinary control flow in all three cases, not a
+Decorator candidate.
+Template Method finding: SKIP — the three "process"-adjacent calls are
+three distinct, unrelated cross-file reference-graph walks, not a shared
+algorithm skeleton with varying steps; there is no "how" worth abstracting.
+
+## Verdict: 4 mechanical findings, all 4 correctly downgraded to SKIP by
+the domain-fit pass — a worked example of why step 4 exists: the mechanical
+scorer's job is to surface the shape, not to be the final word.
+```
+
+This is the calibration this skill exists to enforce: a real structural hit
+is not the same as a real recommendation. The mechanical scorer's honest job
+is surfacing candidates at the stated confidence; the domain-fit pass is
+what turns a candidate into advice.