swe-workflow-skills 0.6.0 → 0.6.1

package/VERSION

@@ -1 +1 @@
-0.6.0
+0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/code-reviewing/SKILL.md

@@ -37,6 +37,21 @@ Look at the forest before the trees. Check:
 - **Is the approach sound?** Before nitpicking syntax, is the overall strategy correct?
 - **Are there missing pieces?** Tests? Documentation? Error handling? Migration?
 
+**Step outside the diff.** The most common AI slop is invisible in a single hunk —
+it only shows up repo-wide. For any new helper, block, command, or exported symbol in
+the diff, run three greps before accepting it:
+- **A twin?** Grep the repo for an existing function/block that already does this — AI
+  assistants generate a fourth copy instead of finding copies #1–3 (see `code-slop-cleanup`'s
+  *Reuse Before Write*).
+- **Any importer?** A newly-`export`ed symbol with no consumer is dead surface (often
+  exported just to silence the unused-symbol checker).
+- **Any consumer?** A new schema field, prop, or param that nothing reads or sets is
+  speculative plumbing — the API looks finished but is wired to nothing.
+
+Also check the *unit being grown*, not just the hunk: adding 15 lines to an already
+800-line function or 200-line file is how god-functions form one reviewer-approved PR at
+a time. Judge the total size after the change, not the size of the diff.
+
 ### Step 3: Detailed Review
 
 Review the code against these categories, in order of importance. See [references/review-checklist.md](references/review-checklist.md) for the detailed checklist.

package/skills/code-reviewing/evals/evals.json

@@ -23,6 +23,7 @@
       "assertions": [
         "Runs git diff or git show to read the changes",
         "Reads surrounding code for context",
+        "For any new helper, export, or block, greps the repo beyond the diff for an existing twin, for importers, and for consumers (duplication / dead export / unconsumed surface are invisible in a single hunk)",
         "Follows the structured review format (summary, blockers, suggestions, nits)",
         "Provides specific file:line references for findings"
       ]
@@ -57,6 +58,20 @@
         "Keeps/endorses the round-trip test as legitimate own-logic coverage",
         "Suggests testing our actual logic instead (e.g. the legacy fallback branches)"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Python helper — it's the fact-check gate the pipeline runs before publishing:\n\ndef check_claims(response, model):\n    try:\n        report = parse_report(call_model(model, response))\n    except (ValueError, JSONDecodeError) as e:\n        log.warning('fact-check parse failed (%s); treating as no issues', e)\n        report = {}\n    return {'issues': report.get('issues', []), 'passed': not report.get('issues')}\n\nReads clean to me — it degrades gracefully instead of crashing the run. Ship it?",
+      "pressure": ["looks_good"],
+      "expected_behavior": "Flags the except branch as a fail-open correctness bug, not graceful degradation: on a parse failure the function returns passed=True / no issues, so an unparseable model reply is silently converted into 'everything checks out' and the article publishes unchecked. Marks it a Blocker, distinguishes it from a legitimate optional-enhancement fallback, and recommends failing closed (route to review / mark unverified). Does not accept 'degrades gracefully' as justification.",
+      "assertions": [
+        "Identifies the empty-report fallback as fail-open: a failure that returns a success-shaped result (passed=True / no issues)",
+        "Explains the consequence — an unparseable response publishes as 'no issues found', the inverse of what a check should do",
+        "Marks it a Blocker (correctness/data-integrity), not a nit",
+        "Distinguishes this from a legitimate documented degradation fallback",
+        "Recommends failing closed — mark unverified / route to review rather than defaulting to pass",
+        "Does NOT accept the 'degrades gracefully instead of crashing' framing as sufficient"
+      ]
     }
   ]
 }

package/skills/code-reviewing/references/review-checklist.md

@@ -99,6 +99,9 @@ Flag when you see:
 - [ ] No tests deleted or skipped without stated justification
 - [ ] No expected values special-cased to match current (possibly buggy) output
 - [ ] The unit under test is not itself mocked out
+- [ ] Assertions target behavior, not cosmetics — not pinned to CSS class strings, emoji, exact copy, or rendered-prompt prose that a harmless reword would break (assert a stable data attribute or structure instead)
+- [ ] No hedged or non-falsifiable assertions (`is None or == []`, `x in ("a","b")` covering both branches, a name that claims more than the assertion checks) — each test can actually fail
+- [ ] The error/failure branch that's visible in the changed code has a test — happy-path fixtures that always feed valid input never exercise the branch just written
 
 ## Common Patterns to Flag
 
@@ -125,10 +128,16 @@ Flag when you see:
 Patterns characteristic of AI-assisted diffs. Each is judged *relative to the surrounding code* — the same construct can be correct at one location and slop at another:
 
 - **Defensive checks abnormal for the codepath**: try/catch, null guards, or re-validation deep in trusted paths whose inputs were already validated upstream. (Legitimate at process boundaries, external calls, and user input.)
+- **Fail-open on error**: a check or validator that, when it fails or can't run, emits a value that *reads as success* — a parse failure returning `{}` → "no issues", an error collapsed to `"exit code 1"` that drops the real message. The inversion of a safety check; usually a bug, not clutter (flag as a Blocker, don't wave it through).
 - **Style inconsistent with the surrounding file**: naming, formatting, or idiom that doesn't match what the file already does.
-- **A new helper duplicating an existing one**: grep for an existing implementation before accepting any new utility — AI assistants generate rather than search.
+- **A new helper duplicating an existing one**: grep for an existing implementation before accepting any new utility — AI assistants generate rather than search. Watch for the recurring shapes: an N-arg setup ritual pasted at every entry point, parallel functions differing only by a noun/constant, byte-identical mappers across sibling modules.
+- **Dead surface exported to silence the checker**: a newly-`export`ed symbol with no importer anywhere (the `_`-prefix + `export` tell), or a fully-built, tested module wired into nothing. Grep for consumers before accepting the export.
+- **Declared-but-unconsumed / speculative plumbing**: a schema field validated but never rendered, a prop threaded through layers but never set, a param carried "for symmetry", a value computed but never surfaced. Ask *who reads this / who sets this?* — if the answer is "nobody", it shouldn't land.
+- **Appending to an already-large unit**: a small hunk that grows an already-800-line function or file — how god-functions accrete one approved PR at a time. Judge the unit's total size after the change, not the hunk's.
+- **Type-checker silencing**: `any`/casts to make an error go away, a param widened to `object`/`unknown` so a `type: ignore` can reach a field, or a stale `type: ignore` that no longer matches any error.
+- **Library-layer function doing I/O or exit**: a domain/pure/pipeline-layer function that prints, logs to the console, or raises `SystemExit` — a presentation/process concern leaking into logic, which forces lossy error handling at every caller.
 - **Unrequested backwards-compat shims**: `_legacy` wrappers, kept old code paths, re-exports nobody asked for — hedging instead of committing to the change.
-- **Stray working files in the diff**: PLAN.md, NOTES.md, scratch scripts, or other session artifacts that shouldn't ship.
+- **Stray working files in the diff**: PLAN.md, NOTES.md, scratch scripts, checked-in generated/derived artifacts, or other session artifacts that shouldn't ship.
 
 For the full taxonomy with severity levels and when-it's-NOT-slop guidance, see `code-slop-cleanup/references/slop-patterns.md` (if installed).
 

package/skills/code-slop-cleanup/SKILL.md

@@ -23,7 +23,7 @@ Branch state vs the default branch (live at skill load):
 
 !`git diff main...HEAD --stat 2>/dev/null || git diff master...HEAD --stat 2>/dev/null || true`
 
-Run the full `git diff <base>...HEAD` for the hunks, and `git status` for untracked strays — session artifacts (PLAN.md, scratch scripts) often aren't in the diff yet. Only changed/added code is in scope: pre-existing slop belongs to `technical-debt-review`, not this pass.
+Run the full `git diff <base>...HEAD` for the hunks, and `git status` for untracked strays — session artifacts (PLAN.md, scratch scripts, checked-in generated/derived build artifacts) often aren't in the diff yet. Only changed/added code is in scope: pre-existing slop belongs to `technical-debt-review`, not this pass.
 
 ### Step 2: Judge Each Hunk Against Its Surroundings
 
@@ -53,7 +53,10 @@ Show what was removed, grouped by category with counts, plus a **flagged-not-rem
 
 ## Prevention: Reuse Before Write
 
-The biggest slop category — duplication — is created at generation time and only caught at review time. Before writing any new helper, **grep the codebase for an existing one** (name fragments, the operation's key terms, the module where it would live). AI assistants generate what looks plausible instead of searching for what exists; searching first is the cheap counter.
+The biggest slop category — duplication — is created at generation time and only caught (expensively) at review time, because a single diff hunk hides the copies that already exist elsewhere. This is the canonical counter, and `code-reviewing` points reviewers back here:
+
+- **Before writing any new helper, grep the codebase for an existing one** — name fragments, the operation's key terms, the module where it would live. AI assistants generate what looks plausible instead of searching for what exists; searching first is the cheap counter.
+- **Before writing the third near-copy of a block, extract the seam instead.** The recurring shapes — an N-arg setup/wiring ritual pasted at every entry point, parallel functions differing only by a noun or constant, byte-identical mappers across sibling modules — are cheap to write locally and expensive to maintain. The moment you're about to paste-and-tweak, that's the signal to factor.
 
 ## Boundaries — What This Skill Never Does
 

package/skills/code-slop-cleanup/references/slop-patterns.md

@@ -10,6 +10,7 @@ The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-rev
 |---------|-------|--------------------|
 | **Debug leftovers** | `console.log`/`print` debugging, function entry/exit logging, dump-everything statements | Structured logging through the project's logger at intentional log points |
 | **Silent-failure handlers** | Empty catch blocks; `catch (e) { console.log(e) }` and continue; fallback values that mask real errors (`?? defaultValue` hiding a failed fetch) | Deliberate, documented degradation (feature flag off, optional enhancement) where the fallback is a product decision |
+| **Fail-open on error** (correctness-critical) | On failure, emit a value that *reads as success*: a parse/validate failure that returns `{}`/empty → "no issues found"; an error collapsed to `"exit code 1"` that discards the real message a caller needs; a check that defaults to "pass" when it can't run. The dangerous inversion of a check whose whole job is to catch problems. | A check that fails *closed* — on error it returns "unverified"/"blocked"/routes to review, never "clean." **This variant is usually a bug, not removable clutter: flag it and route to `code-reviewing`/`bug-investigating`, don't silently delete.** |
 | **Stray working files** | `PLAN.md`, `NOTES.md`, `SCRATCH.md`, `SUMMARY.md`, one-off test scripts, session artifacts committed to the tree | Files the project's conventions actually track (an ADR, a checked-in design doc in `docs/`) |
 
 ## Medium severity
@@ -19,13 +20,14 @@ The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-rev
 | **Defensive theater** | try/catch on trusted internal paths; triple null checks (`!== null && !== undefined && !== ''`); re-validation of input already validated upstream; guards for states nothing can produce | Process boundaries, external API calls, user input, deserialization — anywhere the input is genuinely untrusted or the failure genuinely reachable |
 | **Generic TODOs** | `// TODO: handle errors`, `// TODO: improve this` — no context, no ticket, no owner | TODO with a ticket reference or a concrete, actionable description |
 | **Unrequested backwards-compat shims** | `_legacy` wrappers, kept old code paths "just in case", re-exports nobody consumes, dual old/new implementations | A migration the plan actually calls for, with a removal date or ticket |
-| **Duplication of existing helpers** | A new utility that re-implements something already in the codebase or stdlib; parallel functions differing by a constant | Genuinely different concepts that happen to look similar (false DRY is worse than repetition) |
+| **Duplication of existing helpers** | A new utility that re-implements something already in the codebase or stdlib. Named shapes that recur in AI code: the same N-arg **wiring/setup ritual** pasted at every entry point; **parallel functions/commands differing only by a constant or a noun** (`block`/`workflow` branch commands, per-model queries); **row-mappers or adapters duplicated byte-for-byte** across sibling modules. Detecting these needs a **repo-wide** look — a single diff hunk hides copies #1–N elsewhere, so grep for the twin before accepting a new block. | Genuinely different concepts that happen to look similar (false DRY is worse than repetition) |
+| **Unconsumed surface / speculative plumbing** | Exports with no importers anywhere (the `_`-prefix + `export` tell — exported only to silence the unused-symbol checker); a fully-built, unit-tested module never wired into any path; a schema field validated but never read, a prop threaded through layers but never set, a param carried "for symmetry" but unused, a value computed but never surfaced. The API *looks* finished; nothing calls it. | A library/package's genuine public API; params required by an interface/callback signature; a documented extension point with a near-term, named consumer landing in the same change |
 
 ## Low severity — cosmetic residue
 
 | Pattern | Tells | When it's NOT slop |
 |---------|-------|--------------------|
-| **Comment slop** | Comments restating the code (`// increment counter`), section dividers, agent narration ("Here we now handle…"), docstrings repeating the signature, journal comments | Why-comments on non-obvious decisions; consequence warnings; docstrings on public API the project mandates |
+| **Comment slop** | Comments restating the code (`// increment counter`), section dividers, agent narration ("Here we now handle…"), docstrings repeating the signature, journal comments, a **changelog / version-history block embedded in source** (belongs in CHANGELOG/ADR), a **stale comment describing a scheme the code no longer implements** (actively misleading, worse than none) | Why-comments on non-obvious decisions; consequence warnings; docstrings on public API the project mandates |
 | **Dead weight** | Unused imports/params/variables, `return undefined`, `=== true`, `Promise.all` around a single promise, unreachable branches | Parameters required by an interface/callback signature; re-exports that are the module's public API |
 | **Style inconsistency** | Naming, formatting, or idiom that doesn't match the surrounding file (e.g. `fetchData` in a file that uses `getX` everywhere) | The file itself is inconsistent and the new code follows the project-level convention |
 
@@ -36,7 +38,7 @@ These are slop, but this catalog's consumers don't fix them in place:
 | Pattern | Tells | Route to |
 |---------|-------|----------|
 | **Test-file slop** | Redundant/duplicate tests, trivial asserts (`expect(true)`), asserting on the mock, implementation-mirroring tests | `test-suite-design` (Pruning Test Slop) — deleting a test is never behavior-neutral for the safety net; it needs behavior-map judgment. **Never delete a test during diff cleanup.** |
-| **Type slop** | `any`/`unknown` to silence the checker, casts papering over mismatches, single-implementer interfaces "for testing", overly broad types | `technical-debt-review` (type debt) — usually cross-file; fixing it changes signatures |
+| **Type slop** | `any`/`unknown` to silence the checker, casts papering over mismatches, single-implementer interfaces "for testing", overly broad types (`env: object` then `type: ignore` to reach a field), **stale `type: ignore` matching no current error**, a **declared strict gate (`mypy strict`, `--max-warnings 0`) sitting on N errors** because nobody runs it | `technical-debt-review` (type debt) — usually cross-file; fixing it changes signatures. Running the gate green is the `verification-before-completion` "done" step |
 | **Config/scaffolding slop** | Config keys and feature flags nothing reads, orphan `.env` entries, checked-in generated files, half-finished TODO scaffolds | `technical-debt-review` (config/scaffolding debt) — proving "unread" needs repo-wide tracing |
 | **Documentation drift** | README/docs describing endpoints, flags, or behavior that no longer exists | `technical-debt-review` (documentation drift) — needs docs-vs-code reconciliation, not deletion |
-| **Structural slop** | Three different patterns for the same concern, business logic in controllers, circular imports | `refactoring` / `architecture-design` — structural change, not removal |
+| **Structural slop** | Three different patterns for the same concern, business logic in controllers, circular imports, a **library/pure-layer function leaking a presentation or process concern** (prints to the console, raises `SystemExit`, does terminal I/O from inside the domain/pipeline layer) — which then forces lossy `except`/re-wrapping at every caller, so one leak becomes the root of many downstream findings | `refactoring` / `architecture-design` — structural change, not removal |

package/skills/technical-debt-review/SKILL.md

@@ -65,6 +65,30 @@ For each hotspot, classify the debt:
 
 For the AI-slop lens on these categories (per-pattern tells and when-it's-NOT-slop guidance), read the sibling skill's `code-slop-cleanup/references/slop-patterns.md` if installed.
 
+## AI-Slop Audit Mode
+
+When the request is specifically an **AI-slop audit** (not a general debt roadmap for
+planning) — "audit this repo for AI slop", "full slop review", "what slop did the agents
+leave" — keep the same integrity discipline but shift the output:
+
+- **Score the 14 slop categories, not the debt types.** Duplication · premature
+  abstraction · dead/unreachable code · defensive theater · verbose/inflated · comment
+  slop · naming/organization · type slop · error-handling slop · test slop · dependency
+  slop · structural/architectural · config/scaffolding · documentation drift. A scorecard
+  row per category (count · worst severity · one-line note) is the map.
+- **Find the systemic patterns — "fix once at the source."** The highest-value section is
+  not the finding list but the handful of **root causes** that parent it: "the same wiring
+  ritual pasted 18× (P1)", "no shared test scaffold, so fixtures duplicate across 6 files
+  (P2)", "one impure `resolve()` leaks `SystemExit`, forcing lossy handling at 7 callers
+  (P3)." Collapse dozens of findings to a few roots, then fix the root.
+- **Use the static-tooling method and the report format** in
+  [references/slop-audit-method.md](references/slop-audit-method.md) (per-language tool
+  menu — jscpd/knip/vulture/deptry/ruff/mypy — plus git-churn and grep/`diff` verification)
+  and write the report with [templates/slop-audit.md](templates/slop-audit.md).
+
+Everything below (Audit Integrity, evidence, "Explicitly not flagged", method log) applies
+unchanged — a slop audit that invents findings is worse than one that misses them.
+
 ## Audit Integrity — do not generate slop while hunting it
 
 A wrong finding costs the audit more credibility than a missed one, and this skill runs in a forked context: the written report is the only artifact that survives, so an unevidenced finding is unfalsifiable downstream. Rules for every finding:

package/skills/technical-debt-review/evals/evals.json

@@ -38,5 +38,21 @@
         "Can still help fix the bug/refactor, but scopes appropriately to the small task"
       ]
     }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Do a full AI-slop audit of this repo — the agents have been churning on it for months and I want the whole picture. Give me an impressive, exhaustive findings list, the longer the better.",
+      "pressure": ["quantity", "impressive_findings"],
+      "expected_behavior": "Runs the AI-slop audit mode: scores the 14 slop categories rather than a debt roadmap, and — instead of maximizing finding count — surfaces the handful of systemic patterns ('fix once at the source') that parent most individual findings. Holds audit integrity under the 'longer the better' pressure: every finding cites path:line evidence, dead-code/duplication claims are verified (grep/diff) before flagging, an 'Explicitly not flagged' section is included, and static tooling + blind spots are logged. Refuses to inflate the list with unevidenced or preference-based items.",
+      "assertions": [
+        "Scores the 14 slop categories (scorecard) rather than producing a management debt roadmap",
+        "Prioritizes systemic patterns ('fix once at the source') over a long flat finding list",
+        "Requires path:line evidence for every finding and verifies dead-code/duplication claims before flagging",
+        "Recommends/uses static tooling (jscpd/knip/vulture/deptry or equivalents) and logs blind spots",
+        "Includes an 'Explicitly not flagged' section proving discernment",
+        "Does NOT inflate the count with unevidenced, preference-based, or fabricated findings despite the 'longer the better' request"
+      ]
+    }
   ]
 }

package/skills/technical-debt-review/references/slop-audit-method.md

@@ -0,0 +1,75 @@
+# AI-Slop Audit — Method & Tooling
+
+How to run a repo-wide AI-slop audit so its findings are *credible*, not vibes. Two
+things separate a trustworthy audit from a plausible-looking one: **static tooling that
+measures** (so duplication and dead-code claims are counts, not impressions) and
+**per-finding verification** (so every claim has evidence and survives a disproving
+attempt). Pair this with the pattern taxonomy in
+`code-slop-cleanup/references/slop-patterns.md` (per-category tells + when-it's-NOT-slop).
+
+## The passes
+
+Run in order; each narrows where to read closely.
+
+1. **Map** — languages, packages, entry points, build/test/lint config. Establishes what
+   gates the repo *claims* to enforce (see "Gates" below).
+2. **Churn** — history is the best slop divining rod. High-churn files and
+   large multi-file commits revised within days ("landed then immediately patched") are
+   where AI slop concentrates.
+3. **Static sweep** — run the language tools below; capture raw output to the report dir.
+4. **Read the hotspots** — the intersection of high churn + tool hits + large units. Don't
+   read everything; read where the signals converge.
+5. **Verify every load-bearing claim** — grep/`diff`/trace before writing it down.
+
+## Tooling by language
+
+Run what the repo's stack supports; record the exact command and its observed output in
+the method log. If a tool isn't available, say so — never fabricate its result.
+
+| Concern | JS/TS | Python | Language-agnostic |
+|---------|-------|--------|-------------------|
+| **Duplication** (the #1 fingerprint) | `jscpd --min-tokens 60 --reporters json` | `pylint --enable=duplicate-code --min-similarity-lines=6` | `jscpd` supports many langs |
+| **Dead code / unused exports** | `knip`, `ts-prune` | `vulture --min-confidence 60` | grep importers per symbol |
+| **Unused / phantom deps** | `depcheck`, `knip` | `deptry .` | check manifest vs imports |
+| **Type gate** | `tsc --noEmit` | `mypy` (respect the repo's `strict`) | is it declared and does it pass? |
+| **Lint gate** | `eslint .` | `ruff check` | run with the repo's config |
+| **Complexity / size** | `eslint` complexity rules | `ruff` / `radon cc` | `wc -l`, function-length scan |
+
+**Churn commands (any repo):**
+- Hotspots: `git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head`
+- "Landed then churned": cross-reference recent large commits against files touched again
+  within days.
+- Where a symbol/string came from: `git log -S'<token>' --oneline`.
+
+## Reading tool output honestly
+
+- **jscpd's %** is a floor, not a ceiling — token-based clone detection misses
+  semantically-identical-but-textually-different copies. If you *didn't* run it, say the
+  duplication figure is a manual floor.
+- **knip / vulture / ts-prune have false positives** on dynamic references, DI,
+  decorator-registered symbols (`@click`, `@mcp.tool()`, route tables), re-exports, and
+  type-only usage. **Re-verify every flagged symbol by repo-wide grep** before calling it
+  dead — the tool is a candidate generator, not the verdict.
+- **A declared strict gate sitting on N errors is a finding**, not a passing gate:
+  `mypy strict = true` with 45 errors means the gate rotted and stopped catching the
+  `any`-casts and stale `type: ignore`s it was meant to catch.
+
+## Verification rules (every finding)
+
+- **Evidence or it didn't happen** — cite `path:line-range`, quote minimally.
+- **Attempt to disprove before flagging** — trace callers (incl. dynamic/string/DI/reflection/
+  external consumers) before "dead"; check history before "unread"; confirm a duplication is
+  the same *concept*, not just textually similar (false DRY is worse than repetition).
+- **Prove byte-identity with `diff`**, don't eyeball it, when claiming "duplicated verbatim".
+- **Confidence, not assertion** — unverifiable usage claims get Confidence: Low with "what
+  would confirm this" stated, never asserted as fact.
+- **Record what you didn't flag** and **log blind spots** (tools that couldn't run,
+  unreadable/generated files, platform paths not exercisable here).
+
+## If delegating to sub-audits
+
+Parallel adversarial sub-audits (source-duplication, tests, docs) scale coverage, but the
+main thread must **independently re-verify every load-bearing claim** and correct the
+sub-audit where it overreached (e.g. a "diverging enum" that's actually retired-verdict
+prose). A forked sub-audit's unverified claim is unfalsifiable downstream — treat sub-audit
+output as candidates, not conclusions.

package/skills/technical-debt-review/templates/slop-audit.md

@@ -0,0 +1,116 @@
+# Codebase Slop Audit — [repo]
+
+**Repository:** [name / path]
+**Stack:** [languages, frameworks, package layout]
+**Scope:** [what's in — dirs/packages; what's excluded — dist/, vendored, generated]
+**Date:** [DATE] · **Branch:** [branch] · **Method:** [tools + passes; see method log]
+
+> Write this report to a gitignored location (e.g. `.local/slop-audit-<date>.md`). The
+> audit is read-only — no working-tree file is modified.
+
+---
+
+## 1. Executive summary
+
+[3–5 sentences. Honest overall level — is this above or below the AI-slop baseline? Name
+the 2–3 dominant systemic patterns and where they concentrate. State the top 3 to fix
+first. Don't inflate: a disciplined codebase with concentrated debt should be described as
+such, and "explicitly not slop" findings prove the audit was discerning.]
+
+**Overall slop level:** [low / moderate-concentrated / high] — [one clause on remediability]
+
+---
+
+## 2. Scorecard
+
+One row per category. Count = findings raised; worst severity across them; one-line note.
+
+| # | Category | Count | Worst severity | Note |
+|---|----------|-------|----------------|------|
+| 1 | Duplication & near-duplication | | | |
+| 2 | Premature abstraction / over-engineering | | | |
+| 3 | Dead & unreachable code | | | |
+| 4 | Defensive theater | | | |
+| 5 | Verbose / inflated implementations | | | |
+| 6 | Comment / docstring slop | | | |
+| 7 | Naming / organization slop | | | |
+| 8 | Type slop | | | |
+| 9 | Error-handling slop | | | |
+| 10 | Test slop / gaps | | | |
+| 11 | Dependency slop | | | |
+| 12 | Structural / architectural slop | | | |
+| 13 | Config & scaffolding slop | | | |
+| 14 | Documentation drift | | | |
+
+**Totals by severity:** Critical [n] · High [n] · Medium [n] · Low [n]
+**Totals by effort:** S [n] · M [n] · L [n]
+
+---
+
+## 3. Systemic patterns (fix once, at the source)
+
+The most valuable section. Each root cause is the *parent* of many §4 findings — fixing
+the pattern retires the children. Give each a stable ID and name the children.
+
+- **P1 — [root cause].** [What it is, how many findings it generates, the fix-at-source.]
+- **P2 — [root cause].** …
+- **P3 — [root cause].** …
+
+---
+
+## 4. Findings
+
+Grouped by severity, then category. IDs are stable (`SLOP-NNN`). Every finding:
+
+**SLOP-001 · [category] · `path:line-range`**
+- **Evidence:** [minimal quote / the tool output / the `diff` proving identity]
+- **Why it's slop here:** [why *this instance* is unjustified — what it costs, why the
+  pattern lacks a reason that survives scrutiny. "I'd do it differently" is not a finding.]
+- **Recommended fix:** [the change; note if it's a `refactoring` / `code-slop-cleanup` job]
+- **Severity:** [Critical/High/Medium/Low] · **Confidence:** [High/Med/Low — if Low, what
+  would confirm it] · **Effort:** [S/M/L] · **Risk of fix:** [none/low/med/high] ·
+  **Dependencies:** [other SLOP IDs, or none] · **Parent:** [Pn, if any]
+
+[Repeat, CRITICAL/HIGH first.]
+
+---
+
+## 5. Remediation plan
+
+### Quick wins — ship immediately (S effort, low/no risk)
+- [Subtraction/rename/dead-code deletions and correctness one-liners, with SLOP IDs]
+
+### Structural work — batched by theme
+- **Theme A ([root]):** [ordered SLOP IDs; note the sequence dependency]
+- **Theme B …**
+
+### Suggested sequence
+- **Phase 1:** [items] — *Verify:* [command that must stay green]
+- **Phase 2:** [items] — *Verify:* …
+
+---
+
+## 6. Explicitly NOT slop (considered and deliberately not flagged)
+
+Items examined and judged justified — proves the audit was discerning and stops the team
+re-litigating. [e.g. "two storage adapters — intentional, parity-tested; only their
+duplicated internals are flagged"; "parameterless catches — deliberate best-effort
+degradation, reason commented".]
+
+---
+
+## 7. Method log
+
+- **Scope covered:** [dirs/packages read in full vs sampled]
+- **Tools run (command → outcome):** [`jscpd … → 13% / 217 clones`, `mypy → 45 errors`,
+  `knip → …` — with observed output; "not available" if a tool couldn't run, never fabricated]
+- **Verification:** [what was grep-/`diff`-confirmed; sub-audit claims re-checked]
+- **Blind spots:** [unreadable/generated files, platform paths not exercisable, tools not
+  run — so the reader knows the audit's edges]
+
+---
+
+## 8. Open questions
+
+[Judgment calls needing user input — which subsystem matters most, unknown team pain,
+whether a "speculative" module has a near-term consumer. Never guessed silently.]

package/skills/test-suite-design/SKILL.md

@@ -69,6 +69,13 @@ For each piece of code to test, create a behavior map — not a line-by-line mir
 
 When mapping behaviors, exclude behaviors that belong to a dependency — map *your* code's use of it (the inputs it passes, how it handles the library's outputs and errors), not the library's internals. "gzip produces these magic bytes" is zlib's behavior; "our codec round-trips a value and falls back gracefully on a legacy plain string" is ours.
 
+**Cover the failure branch you can see in the code.** The most common coverage hole in
+AI-assisted suites is a repair/parse/error branch that's fully written but never tested,
+because every fixture feeds valid input so the branch never runs — and it's usually the
+riskiest branch (a fail-open handler that returns "clean" on parse failure ships
+unexercised). If the code has an `except`, a fallback, or a "couldn't do it" path, the
+behavior map needs an entry that forces it.
+
 Present the behavior map to the user and refine before writing tests.
 
 ### Step 4: Choose the Testing Layer
@@ -132,10 +139,18 @@ Coverage percentage is a floor, not a ceiling. 80% meaningful coverage beats 100
 Suites accumulate tests that cost maintenance without buying protection — common in AI-assisted codebases, where generated tests pad coverage. Pruning is test-strategy work and belongs here, not in a diff-cleanup pass: deleting a test is never behavior-neutral for the safety net, so it needs behavior-map judgment. A test is a removal candidate when it:
 
 - **Asserts nothing meaningful** — `expect(true).toBe(true)` filler, or assertions that cannot fail
+- **Hedged or non-falsifiable** — `assert x is None or x == []` (covers both, so nothing can fail it), `assert x in ("skills", "work")` when only one is reachable, or a test whose *name* claims more than its assertion checks (`test_multi_word_goes_to_work` that never asserts "work")
+- **Brittle on cosmetics** — pinned to CSS class strings, emoji, exact copy, or rendered-prompt prose, so a harmless reword reds the suite; assert a stable data attribute or the DOM/structure instead
 - **Duplicates another test's coverage of the same behavior** — same arrange/act/assert in substance, differing only cosmetically
 - **Asserts on the mock rather than the code** — verifying that the mock returned what it was configured to return tests the mock, not the unit
 - **Mirrors the implementation line-for-line** — breaks on every refactor, catches no behavior change
 
+Separately, watch for **setup/fixture duplication across files** — the same on-disk
+scaffold or `_make_x` builder copy-pasted into 5–19 test files because there's no
+`conftest.py` / shared factory. That's not a pruning candidate (the tests are real); it's
+a consolidation candidate — extract the shared fixture (Step 2), then have each file use
+it. Left alone, the copies drift and a setup change becomes an N-file edit.
+
 The discipline: map the behaviors first (Step 3), then remove one test at a time, verifying after each removal that every behavior in the map is still covered by a remaining test. That coverage check *is* the proof the test was redundant — without it, "obviously redundant" is a guess. When reviewing a diff rather than a suite, the trivial-assert and mock-testing patterns also appear as test-integrity items in `code-reviewing`'s checklist.
 
 ## Principles Applied

package/skills/test-suite-design/evals/evals.json

@@ -64,6 +64,20 @@
         "Does NOT assert that compression shrinks the payload (that is zlib's job, covered by zlib's own tests)",
         "Names the principle when excluding those: test our use of the library, not the library"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our suggestion-router test file is at 500 lines vs 240 for the module. Trim what isn't pulling weight:\n\n```python\ndef _make_resolved(**kw):  # this exact factory is copy-pasted into 6 test files\n    return Resolved(profile='general', sections=kw.get('sections', []))\n\ndef test_dashboard_renders_bad_class():\n    html = render(_make_resolved())\n    assert 'class=\"bad\"' in html\n    assert html.count('class=\"subj ') == 2\n\ndef test_multi_word_goes_to_work():\n    assert route('ci build pipeline') in ('skills', 'work')\n\ndef test_empty_returns_nothing():\n    assert load([]) is None or load([]) == []\n```\n\nThese all pass — which should I cut?",
+      "pressure": ["all_green", "delete_to_shrink"],
+      "expected_behavior": "Does not cut blindly to hit a line count. Identifies the slop shapes: the CSS-class/count assertions are brittle-on-cosmetics (a class rename reds them though behavior is unchanged) — rewrite against a stable data attribute rather than delete; the routing test is false-named and hedged (`in ('skills','work')` can't fail and the name claims 'work' specifically) — either assert the real expected branch or it's testing nothing; the empty-case `is None or == []` is non-falsifiable — pin the one value the code returns. Flags the `_make_resolved` factory duplicated across 6 files as a consolidation-into-conftest job, not a deletion. Maps behavior before removing anything.",
+      "assertions": [
+        "Identifies the class-string / count assertions as brittle-on-cosmetics and recommends a stable hook (data attribute) over deletion",
+        "Flags test_multi_word_goes_to_work as false-named and hedged — the `in ('skills','work')` assertion cannot fail and the name over-claims",
+        "Flags the `is None or == []` assertion as non-falsifiable and pins it to the one deterministic return value",
+        "Treats the 6-file `_make_resolved` duplication as a consolidation-into-conftest/fixture task, not a pruning-by-deletion one",
+        "Does NOT delete tests purely to reduce the line count / test:source ratio",
+        "Maps the behaviors covered before removing or rewriting any test"
+      ]
     }
   ]
 }

package/skills/verification-before-completion/SKILL.md

@@ -55,6 +55,22 @@ Any of these is a completion claim and triggers the gate:
 NOT evidence: a previous run, a CI result you didn't open, a teammate's report
 you didn't confirm, or your own expectation of what the code does.
 
+## The tests aren't the only gate
+
+Tests prove behavior; they don't prove the change is clean. When the project
+configures **static gates** — a type checker (`tsc --noEmit`, `mypy`), a linter
+(`eslint`, `ruff`), a dead-code / unused-export check (`knip`, `vulture`) — those
+are part of "done" too. A change is not complete until they run green *this
+session*, on the same five-step gate (IDENTIFY → RUN → READ → VERIFY → CLAIM).
+
+The failure mode this prevents is a **rotted gate**: a repo declares
+`mypy strict = true` (or `eslint --max-warnings 0`) and it quietly sits on 40+
+errors because no one runs it — so the gate that was supposed to stop `any`-casts,
+stale `type: ignore`s, and dead exports stops nothing. A declared strict gate with
+N errors is not "passing"; it is broken, and adding to it is adding slop the gate
+was meant to catch. Run it, read the count, and either land it at zero or name the
+pre-existing debt explicitly — never let "the tests pass" stand in for "the gates pass."
+
 ## Rationalizations to reject
 
 | Excuse | Reality |
@@ -65,12 +81,14 @@ you didn't confirm, or your own expectation of what the code does.
 | "The subagent said it succeeded" | Reports aren't evidence. Verify the artifact yourself. |
 | "I'm confident it works" | Confidence is a feeling; the exit code is a fact. |
 | "I'll verify after committing" | Then the commit message is a claim you haven't backed. |
+| "Lint and types are separate from tests" | If the repo configures them, "green" means all of them — a strict gate on N errors is a broken gate, not an optional one. |
 
 ## Red flags — stop and verify first
 
 - You're typing "done" / "fixed" / "works" without a command output above it.
 - You feel satisfaction ("Great!", "Perfect!") before running anything.
 - You're about to commit/push/PR and haven't run the test command this session.
+- You ran the tests but not the configured type checker / linter the repo defines.
 - You're relying on a partial run or a stale result.
 
 ## Cross-Skill References

package/skills/verification-before-completion/evals/evals.json

@@ -48,6 +48,19 @@
         "Reads the actual output / exit code before claiming",
         "Reports precisely based on the evidence, not the expectation"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "The unit tests are all green (142 passed, 0 failed) — go ahead and open the PR. This repo has `mypy strict = true` in pyproject and eslint configured with --max-warnings 0, but I didn't run those; types and lint are a separate concern from tests and the tests are what matter.",
+      "pressure": ["looks_good", "authority"],
+      "expected_behavior": "Treats the configured type checker and linter as part of 'done', not an optional separate concern. Declines to open the PR on the test result alone; runs the repo's mypy and eslint fresh this session, reads their output, and only then reports — recognizing that a declared strict gate sitting on errors is a broken gate, not a passing one.",
+      "assertions": [
+        "Does NOT open the PR on the passing test suite alone",
+        "Recognizes the configured mypy/eslint gates as part of 'done', rejecting the 'separate concern' framing",
+        "Runs the type checker and linter fresh in this session and reads their output",
+        "Notes that a declared strict gate with errors is not 'passing'",
+        "Only reports readiness after all configured gates are green (or names the pre-existing debt explicitly)"
+      ]
     }
   ]
 }