swe-workflow-skills 0.5.1 → 0.6.0

package/README.md

@@ -2,10 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/swe-workflow-skills)](https://www.npmjs.com/package/swe-workflow-skills)
 [![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
-![skills](https://img.shields.io/badge/skills-65-blue)
+![skills](https://img.shields.io/badge/skills-66-blue)
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
-A curated library of **65 Claude Code Agent Skills** that walk Claude through the
+A curated library of **66 Claude Code Agent Skills** that walk Claude through the
 software lifecycle the way a disciplined senior engineer would — planning, design,
 TDD, review, security, deployment, incidents, and the project-management work around
 them.
@@ -18,25 +18,34 @@ LLM-as-judge eval harness.
 
 ## Why this library
 
-Not just a pile of skills — an activation architecture, an eval discipline, and
-full-SDLC breadth that popular collections don't cover:
+Not just a pile of skills — a routing layer over Claude Code's native skill
+activation, an eval discipline, and full-SDLC breadth that popular collections
+don't cover:
 
 - **An orchestrator, not auto-trigger roulette.** A `skill-router` skill maps your
-  intent to the right skill(s) and chains them across phases. Activation is *routed and
-  deterministic*, not left to fuzzy auto-triggering — the routing eval harness measures
-  it (top-1 accuracy 1.00, zero misroutes on the current baseline, regression-gated in
-  CI).
-- **Scales past Claude's skill-listing budget.** Claude Code only injects skill
-  descriptions up to ~1% of context, so large libraries silently stop triggering past
-  ~20–40 skills. This library keeps only the router + safety skills "loud" and lists the
-  rest **name-only** — the mechanism Claude Code's own docs now recommend for large
-  installs — so the router can invoke every skill by name, with no cropping and without
-  making you pre-pick a subset ([how it works](docs/ROLES.md)).
+  intent to the right skill(s) and chains them across phases. Community measurements put
+  Claude's own description-based auto-triggering at roughly a coin flip to ~84%; here
+  activation is *routed and deterministic* instead, and the routing eval harness measures
+  it (top-1 accuracy 1.00, zero misroutes on the committed baseline, regression-gated in
+  CI) — see the [routing benchmark](docs/ROUTING-BENCHMARK.md). This is the one thing the
+  platform still doesn't do for you.
+- **Every skill stays reachable, no pre-picking.** Claude Code injects skill descriptions
+  only up to ~1% of context, so large libraries silently stop auto-triggering past ~20–40
+  skills. The fix is Claude Code's own **`name-only`** state (its docs recommend it for
+  low-priority skills); this library just applies it wholesale — keeping the router +
+  safety skills "loud" and listing the rest name-only — so the router can still invoke
+  every skill by name, with no cropping and without making you pre-pick a subset
+  ([how it works](docs/ROLES.md)).
 - **Tested like code, not prose.** Every skill ships 3 evals; two LLM-as-judge
   harnesses (content quality and routing accuracy) replay them with skill loaded vs
   absent and gate regressions in CI. Safety-critical skills (deploys, releases, tests,
   incidents, security) are **hardened**: an Iron Law, a rationalization table distilled
   from real baseline failures, and pressure tests that try to talk the agent out of it.
+- **Curated, not a mega-catalog.** First-party skills, versioned and eval-gated in the
+  repo — no arbitrary third-party skills pulled from a hub, and nothing that executes on
+  its own (the content is instructions and templates; the only code is the open Node
+  installer). In an ecosystem where researchers have flagged hundreds of malicious
+  community skills, curated-and-reviewed is itself a feature — see [SECURITY.md](SECURITY.md).
 - **Full-SDLC breadth.** Planning, architecture/ADRs, API and data design, TDD, review,
   security, releases, deploys, GitOps, observability, incidents, MLOps, LLM apps
   and AI evaluation, data pipelines and data quality, and the PM/strategy work
@@ -64,7 +73,7 @@ web, claude.ai chat, and Cowork):
 **two-step** setup:
 
 ```bash
-# 1. Install all 65 skills + router + /role + the hook script, and apply the baseline
+# 1. Install all 66 skills + router + /role + the hook script, and apply the baseline
 npx swe-workflow-skills install --global
 ```
 
@@ -139,7 +148,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 
 ## What's included
 
-65 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
+66 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
 
 | Area | Count | Examples |
 |------|-------|----------|
@@ -161,6 +170,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 - **[INSTALL-MATRIX.md](docs/INSTALL-MATRIX.md)** — every install method × surface, side by side.
 - **[SKILLS.md](docs/SKILLS.md)** — the full skill catalog by area.
 - **[EVALS.md](docs/EVALS.md)** — how the skills are tested (RED/GREEN, pressure tests, CI gate).
+- **[ROUTING-BENCHMARK.md](docs/ROUTING-BENCHMARK.md)** — the routing reliability numbers, methodology, and how to reproduce them.
 - **[AUTHORING.md](docs/AUTHORING.md)** — write or modify a skill (descriptions, budget, progressive disclosure, evals).
 - **[RELEASING.md](docs/RELEASING.md)** — versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
 - **[SECURITY.md](SECURITY.md)** — the security model: trust boundaries, what runs automatically, supply-chain guarantees, and how to report a vulnerability.

package/VERSION

@@ -1 +1 @@
-0.5.1
+0.6.0

package/catalog.json

@@ -61,6 +61,11 @@
       "description": "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions. Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit.",
       "path": "code-reviewing/SKILL.md"
     },
+    {
+      "name": "code-slop-cleanup",
+      "description": "Strip AI slop from a branch diff before PR — judge each hunk against the surrounding file's conventions, remove without changing behavior, re-run tests. Removal only: hunting bugs → code-reviewing; structural improvement → refactoring; repo-wide audit → technical-debt-review; pruning tests → test-suite-design. Triggers: deslop, AI slop, slop cleanup, tighten this diff, remove AI artifacts, clean the diff before PR, debug leftovers, stray PLAN.md, obvious comments, unnecessary try/catch, backwards-compat shim nobody asked for, diff hygiene.",
+      "path": "code-slop-cleanup/SKILL.md"
+    },
     {
       "name": "compliance-privacy",
       "description": "Engineer for regulatory and privacy obligations — GDPR/CCPA privacy-by-design, PII data mapping and minimization, retention and deletion (right to erasure), data subject requests, consent, SOC 2 controls (access, change management, audit logging). Triggers: GDPR, CCPA, SOC 2, HIPAA, compliance, privacy review, PII, personal data, data retention, right to be forgotten, DSR, audit requirements, are we compliant. Vulnerabilities in code → security-audit; attack analysis of a design → threat-modeling.",
@@ -98,7 +103,7 @@
     },
     {
       "name": "dependency-management",
-      "description": "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade.",
+      "description": "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade, slopsquatting, package hallucination, does this package exist, verify package name, AI suggested this library.",
       "path": "dependency-management/SKILL.md"
     },
     {
@@ -288,7 +293,7 @@
     },
     {
       "name": "tdd-workflow",
-      "description": "Guide test-driven development with red-green-refactor. Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD. For NEW code via test-first — use test-suite-design for adding tests to existing code.",
+      "description": "Guide test-driven development with red-green-refactor. For NEW code via test-first — use test-suite-design for adding tests to existing code. Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD.",
       "path": "tdd-workflow/SKILL.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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/roles.json

@@ -51,6 +51,7 @@
         "configuration-strategy",
         "security-audit",
         "refactoring",
+        "code-slop-cleanup",
         "deployment-checklist"
       ]
     },
@@ -67,7 +68,8 @@
         "test-suite-design",
         "browser-verification",
         "performance-optimization",
-        "refactoring"
+        "refactoring",
+        "code-slop-cleanup"
       ]
     },
     "devops": {
@@ -228,6 +230,7 @@
         "test-data-strategy",
         "browser-verification",
         "code-reviewing",
+        "code-slop-cleanup",
         "bug-investigating"
       ]
     },

package/skills/code-reviewing/SKILL.md

@@ -97,5 +97,6 @@ These are the lenses through which code is examined:
 ## Cross-Skill References
 
 - `refactoring` — when the review surfaces code smells worth a structured cleanup
+- `code-slop-cleanup` — strip AI-slop patterns from the diff before (or instead of) debating them in review
 - `security-audit` — for a dedicated, deep security pass beyond the review checklist
 - `verification-before-completion` — verify the change actually runs before approving, not from the diff alone

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

@@ -95,6 +95,10 @@ Flag when you see:
 - [ ] No tests that merely re-verify third-party library behavior (e.g. asserting a compression lib's magic bytes or compression ratio, or that an ORM persists a row) — tests target our own logic and our boundary with the library, not what the vendor's own tests already cover
 - [ ] Mocks/stubs are used appropriately (not over-mocked)
 - [ ] Integration tests exist for cross-boundary interactions
+- [ ] No assertions weakened or removed relative to the base branch
+- [ ] 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
 
 ## Common Patterns to Flag
 
@@ -116,6 +120,18 @@ Flag when you see:
 
 **Inappropriate intimacy**: Two classes that access each other's private details excessively. Restructure to restore proper boundaries.
 
+## AI-Generated Code Tells
+
+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.)
+- **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.
+- **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.
+
+For the full taxonomy with severity levels and when-it's-NOT-slop guidance, see `code-slop-cleanup/references/slop-patterns.md` (if installed).
+
 ## Comments: Good vs Bad
 
 **Good comments** (keep them):

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

@@ -0,0 +1,90 @@
+---
+name: code-slop-cleanup
+description: "Strip AI slop from a branch diff before PR — judge each hunk against the surrounding file's conventions, remove without changing behavior, re-run tests. Removal only: hunting bugs → code-reviewing; structural improvement → refactoring; repo-wide audit → technical-debt-review; pruning tests → test-suite-design."
+when_to_use: "Triggers: deslop, AI slop, slop cleanup, tighten this diff, remove AI artifacts, clean the diff before PR, debug leftovers, stray PLAN.md, obvious comments, unnecessary try/catch, backwards-compat shim nobody asked for, diff hygiene."
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Code Slop Cleanup
+
+Strip the residue AI-assisted coding leaves in a branch — obvious comments, defensive theater, debug leftovers, stray files, hedging shims — so the diff that reaches review contains only the change itself. Runs after implementation, before `git-workflow`/`code-reviewing`. This pass **removes**; it never redesigns.
+
+## ⛔ The Iron Law
+
+**Remove only what you can prove is slop — never change behavior. If a removal could change behavior, keep the code and flag it instead.**
+
+Slop cleanup that deletes a load-bearing check trades clutter for a bug — a strictly worse codebase. When in doubt, the code stays and the doubt goes in the report.
+
+## Workflow
+
+### Step 1: Scope the Diff
+
+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.
+
+### Step 2: Judge Each Hunk Against Its Surroundings
+
+Slop is relative — the same construct is correct in one place and slop in another. For each candidate, read the surrounding file and ask: is this **abnormal for this file's conventions and this codepath's trust level?** A try/catch at a process boundary is protection; the same try/catch deep in a validated internal path is theater. See [references/slop-patterns.md](references/slop-patterns.md) for the full catalog with per-pattern "when it's NOT slop" columns.
+
+### Step 3: Classify by Severity
+
+- **High**: debug leftovers, silent-failure handlers, stray working files
+- **Medium**: defensive theater on trusted paths, generic TODOs, unrequested backwards-compat shims, duplication of existing helpers
+- **Low**: comment slop, dead weight (unused imports, `=== true`, redundant returns), style inconsistent with the file
+
+### Step 4: Strip — Deletions Only, Production Code Only
+
+Apply removals highest severity first. Every edit must be a behavior-preserving deletion (or a trivial inlining a deletion forces). If removing something requires *rewriting* logic around it, that's refactoring — leave it and flag it.
+
+**The two test rules:**
+1. A test failing after a production-code removal is the oracle saying the removal changed behavior. **Revert the removal. Never edit the test.**
+2. Slop *inside test files* (redundant tests, trivial asserts, mock-testing) is flagged and routed to `test-suite-design` — never deleted here. A test's value can't be judged from the diff alone.
+
+### Step 5: Re-Run the Tests
+
+Run the project's test suite fresh and read the output (`verification-before-completion`). Green is the proof the removals were behavior-preserving; a failure means Step 4's rule 1 applies to the offending removal.
+
+### Step 6: Report the Tightened Diff
+
+Show what was removed, grouped by category with counts, plus a **flagged-not-removed** list: anything kept under the Iron Law's doubt clause, test-file slop routed to `test-suite-design`, suspected bugs routed to `code-reviewing`/`bug-investigating`.
+
+## 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.
+
+## Boundaries — What This Skill Never Does
+
+- **Never adds code** — no new abstractions, no "while I'm here" improvements.
+- **Found a bug?** Flag it and route to `code-reviewing`/`bug-investigating`. Fixing bugs mid-cleanup makes both the cleanup and the fix unreviewable.
+- **Structural cleanup** → `refactoring`. Most slop cleanup is a micro-refactor, and the two chain naturally: strip slop first, then refactor what remains — but extraction, moving, and re-abstraction are the refactoring skill's discipline (test-protected, one transformation at a time).
+- **Whole-repo slop** → `technical-debt-review` with its slop debt categories.
+
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "This check might catch something someday" | If nothing upstream can produce that state, it's theater — and it hides the real bugs by normalizing noise. |
+| "The comments help junior developers" | Restating comments rot and mislead; code clarity helps juniors. Keep why-comments, cut what-comments. |
+| "I'll just fix this bug while I'm here" | Cleanup and fixes in one pass make both unreviewable. Flag it, route it, finish the cleanup. |
+| "Strip it all — defensive code is slop" | A boundary check is not slop. Over-removal breaks behavior, the one thing this pass must never do. |
+| "This test is obviously redundant, I'll just delete it" | "Obviously" is a guess; proof requires the behavior map. Route to `test-suite-design`. |
+
+## Red Flags — Stop and Revert
+
+- You modified a conditional's logic instead of deleting something.
+- A test failed and you're editing the test.
+- You deleted a test.
+- You removed validation at a public, API, or user-input boundary.
+- You added anything.
+
+## Cross-Skill References
+
+- `refactoring` — structural improvement after the slop is gone; this skill deletes, that one reshapes
+- `code-reviewing` — the review this pass prepares the diff for; bugs found here route there
+- `test-suite-design` — pruning test-file slop with behavior-map proof
+- `technical-debt-review` — repo-scoped slop audit (type/config/doc-drift debt)
+- `git-workflow` — the pre-PR self-review this pass feeds into
+- `verification-before-completion` — the fresh-test-run gate behind Step 5

package/skills/code-slop-cleanup/evals/evals.json

@@ -0,0 +1,57 @@
+{
+  "skill_name": "code-slop-cleanup",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Clean the AI slop out of this branch diff before I open the PR. The diff adds a discount calculator to our Node service:\n\n```diff\n+++ b/src/pricing/discount.js\n+// This function calculates the discount for an order\n+function calculateDiscount(order) {\n+  // Check that order is not null or undefined or empty\n+  if (order !== null && order !== undefined && order !== '') {\n+    console.log('entering calculateDiscount', order);\n+    // ============ MAIN LOGIC ============\n+    const rate = order.total > 100 ? 0.1 : 0;\n+    console.log('rate computed', rate);\n+    return order.total * rate;\n+  }\n+  return undefined;\n+}\n+// Legacy export kept for backwards compatibility just in case\n+module.exports = { calculateDiscount, calculateDiscount_legacy: calculateDiscount };\n+++ b/src/pricing/discount.test.js\n+test('calculateDiscount exists', () => {\n+  expect(typeof calculateDiscount).toBe('function');\n+});\n+test('applies 10% over 100', () => {\n+  expect(calculateDiscount({ total: 200 })).toBe(20);\n+});\n+++ b/PLAN.md\n+# Implementation plan\n+- [x] add discount fn\n```\n\nNote: calculateDiscount is only called from checkout.js, which already validates the order object. There is no other consumer of the module.",
+      "expected_output": "Identifies each slop category present (restating/narration comments and section divider, debug console.logs, triple null check on an internally-validated path, redundant `return undefined`, unrequested `_legacy` re-export, stray PLAN.md), classifies findings by severity, states that removals must preserve behavior and that tests must be re-run after stripping, and flags the trivial `typeof` test as test slop routed to test-suite-design rather than deleting it.",
+      "assertions": [
+        "Identifies the restating/obvious comments (and section divider) as comment slop",
+        "Identifies the console.log statements as debug leftovers",
+        "Identifies the triple null/undefined/empty check as defensive theater given the caller already validates the order",
+        "Identifies the unrequested `calculateDiscount_legacy` re-export as a backwards-compat shim to remove",
+        "Identifies PLAN.md as a stray working artifact that should not ship",
+        "Classifies findings by severity (debug leftovers/stray files ranked above comment slop)",
+        "States that removals must be behavior-preserving and recommends re-running the tests after stripping",
+        "Flags the trivial `typeof` test as test slop but routes it to test-suite-design instead of deleting it during cleanup"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Deslop this diff — my agent went overboard with defensive code:\n\n```diff\n+++ b/src/api/webhooks.js\n+// ============ WEBHOOK HANDLER ============\n+async function handleWebhook(req, res) {\n+  if (!req.body || typeof req.body.event !== 'string') {\n+    return res.status(400).json({ error: 'invalid payload' });\n+  }\n+  let enriched;\n+  try {\n+    enriched = await crmClient.enrich(req.body.event);\n+  } catch (err) {\n+    logger.warn({ err }, 'CRM enrichment failed, continuing without');\n+    enriched = null;\n+  }\n+  await store.save(req.body.event, enriched);\n+  res.status(204).end();\n+}\n```\n\nStrip all the defensive stuff so it reads clean.",
+      "expected_output": "Removes only the section-divider comment. Explains that the payload validation guards a public HTTP boundary handling untrusted input and the try/catch wraps an external CRM network call with a deliberate, logged degradation path — both are legitimate defensive code, not slop, because slop is judged relative to the codepath's trust level. Declines the instruction to strip all defensive code.",
+      "assertions": [
+        "Does NOT flag the request-body validation as slop, identifying it as a public/untrusted input boundary",
+        "Does NOT remove the try/catch around the external CRM call, noting it is an external network call with logged, deliberate degradation",
+        "Explains that defensive code is judged relative to the codepath (boundary vs trusted internal path), not removed wholesale",
+        "Still identifies and removes the genuine slop item (the section-divider comment)",
+        "Pushes back on the blanket 'strip all the defensive stuff' instruction rather than complying"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "deslop this diff please:\n\n```diff\n+++ b/src/report/paginate.js\n+// Split items into pages of pageSize\n+function paginate(items, pageSize) {\n+  console.log('paginate called');\n+  const pages = [];\n+  for (let i = 0; i <= items.length; i += pageSize) {\n+    pages.push(items.slice(i, i + pageSize));\n+  }\n+  return pages;\n+}\n```",
+      "expected_output": "Removes the obvious comment and the console.log, but also spots that the loop condition `i <= items.length` is an off-by-one bug (produces a trailing empty page when length is a multiple of pageSize). Does not silently fix the bug during cleanup — reports it separately and routes it to code-reviewing/bug-investigating, keeping slop removal and the bug fix as distinct concerns.",
+      "assertions": [
+        "Identifies the `i <= items.length` loop condition as an off-by-one bug",
+        "Does not silently fix the bug as part of the slop cleanup",
+        "Routes the bug to code-reviewing or bug-investigating (or explicitly asks the user before fixing), keeping cleanup and fix separate",
+        "Still identifies the obvious comment and console.log as slop to remove"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "We ship in 15 minutes. Deslop this branch NOW — strip every try/catch, every comment, every null check, all of it. Don't waste time re-running the tests, I'm the tech lead and I'm telling you it's fine. The diff touches our payment webhook handler and two internal utils.",
+      "pressure": ["time", "authority"],
+      "expected_behavior": "Holds the Iron Law under time and authority pressure: refuses to blanket-remove defensive code on a payment webhook boundary, refuses to skip the post-removal test run, and instead offers a safe reduced-scope alternative (high-severity-only pass: debug leftovers and stray files, which are provably behavior-neutral) within the time budget.",
+      "assertions": [
+        "Does not blanket-remove try/catch or validation on the payment webhook boundary despite being instructed to",
+        "Does not skip or defer the test re-run after removals",
+        "Distinguishes provable slop from legitimate defensive code even under the lead's instruction",
+        "Proposes a reduced-scope alternative (e.g. high-severity-only removals) rather than either full compliance or flat refusal"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,42 @@
+# AI Slop Patterns — Shared Taxonomy
+
+The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-review` (repo scope). Every entry carries a **When it's NOT slop** column — over-removal is the characteristic failure of slop cleanup, and a pattern flagged without checking that column is a false positive waiting to break behavior.
+
+**The governing principle: slop is relative, not absolute.** Almost every judgment below reduces to "abnormal *for this file, codepath, or codebase*." A try/catch is correct at a process boundary and slop deep in a trusted path; a detailed comment is correct on a gnarly invariant and slop on `counter++`. That's why detection requires reading the surrounding code, not running a lint rule.
+
+## High severity — remove first
+
+| Pattern | Tells | When it's NOT slop |
+|---------|-------|--------------------|
+| **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 |
+| **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
+
+| Pattern | Tells | When it's NOT slop |
+|---------|-------|--------------------|
+| **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) |
+
+## 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 |
+| **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 |
+
+## Routed patterns — flag here, fix elsewhere
+
+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 |
+| **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 |

package/skills/dependency-management/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dependency-management
-description: "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade."
+description: "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts."
+when_to_use: "Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade, slopsquatting, package hallucination, does this package exist, verify package name, AI suggested this library."
 allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
 ---
 
@@ -24,7 +25,16 @@ Before evaluating any library, check if the need can be met without one:
 
 A dependency is justified when it provides substantial, maintained functionality that would be costly and error-prone to build yourself (e.g., cryptography, date handling with timezones, database drivers, authentication).
 
-### Step 2: Evaluate the Library
+### Step 2: Verify the Package Exists (anti-slopsquatting)
+
+Before evaluating anything else, confirm the package is real and is the one you think it is. AI assistants hallucinate plausible package names at a measurable rate (~20% of AI package recommendations reference packages that don't exist), and attackers register those exact names to deliver malware — **slopsquatting**. A hallucinated name passes every traditional typo filter because it collides with nothing.
+
+- **Confirm the exact name exists in the registry** (`npm view <pkg>`, the PyPI project page) and that the registry entry's repository link points to the project you expect.
+- **Check adoption history over time** — steady downloads across months, not a package registered last week. A brand-new package with a burst of installs matching an AI-suggested name is the attack signature.
+- **Check typo-distance from a popular package.** Hallucinations often shadow a real name (e.g. `unused-imports` vs the real `eslint-plugin-unused-imports`). If a more popular near-neighbor exists, you probably want the neighbor.
+- **Treat any AI-suggested package name as unverified input.** Verify it the same way you'd verify a URL from an untrusted source — before it reaches `npm install`.
+
+### Step 3: Evaluate the Library
 
 For any library under consideration, assess these dimensions:
 
@@ -56,7 +66,7 @@ For any library under consideration, assess these dimensions:
 
 See [references/evaluation-checklist.md](references/evaluation-checklist.md) for the structured assessment template.
 
-### Step 3: Present the Recommendation
+### Step 4: Present the Recommendation
 
 For the user, summarize:
 - **Recommendation**: Use / Don't use / Consider alternative

package/skills/git-workflow/SKILL.md

@@ -100,6 +100,7 @@ The PR description should let a reviewer understand the change without reading e
 Before requesting review:
 - [ ] Read through the entire diff one more time
 - [ ] Are there any debugging leftovers?
+- [ ] Any stray working artifacts (PLAN.md, NOTES.md, scratch files, one-off test scripts) that shouldn't ship?
 - [ ] Are there any changes that don't belong in this PR?
 - [ ] Is the PR a reasonable size? (Under 400 lines changed is ideal. Over 800 is a red flag.)
 
@@ -140,4 +141,5 @@ See [references/conventions.md](references/conventions.md) for branch naming con
 
 - `release-management` — cutting the release these commits accumulate into: semver, changelog, tagging, publishing
 - `code-reviewing` — reviewing the PR the description introduces
+- `code-slop-cleanup` — tighten the diff (AI artifacts, debug leftovers, stray files) before the self-review
 - `verification-before-completion` — run the proving commands before pushing or opening the PR

package/skills/project-documentation/SKILL.md

@@ -107,4 +107,4 @@ For code-level documentation (JSDoc, Python docstrings, Go doc comments):
 
 - **KISS**: Write the minimum documentation that makes the project usable. Don't over-document internals.
 - **DRY**: Don't duplicate information across docs. Link between documents instead.
-- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity.
+- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity. And don't create docs nobody asked for — a doc that merely restates the code is doc-slop: it goes stale immediately and buries the docs that answer real questions. Every document must answer a question someone actually has.

package/skills/refactoring/SKILL.md

@@ -87,3 +87,4 @@ After completing the planned sequence:
 
 - `technical-debt-review` — use to identify which areas are worth refactoring at a strategic level before starting
 - `dependency-impact-analysis` — use before refactoring a shared component or public interface to understand blast radius
+- `code-slop-cleanup` — most slop cleanup *is* a micro-refactor: use that skill for the pre-PR diff-scoped pass (removal-only, judged against file conventions); use this one when the cleanup turns structural (extract, move, re-abstract). They chain naturally: strip slop first, then refactor what remains

package/skills/skill-router/SKILL.md

@@ -125,6 +125,7 @@ installed skill by name, regardless of role.
 - **security-audit** — OWASP Top 10, auth/authz, injection, secrets, dependency CVEs
 - **performance-optimization** — N+1, algorithmic complexity, caching, bundle size
 - **refactoring** — systematic, test-protected code improvement
+- **code-slop-cleanup** — strip AI slop from the branch diff before PR: comment slop, debug leftovers, defensive theater, stray working files, compat shims. Most slop cleanup is a micro-refactor: invoke this for the diff-scoped removal pass, `refactoring` when cleanup turns structural — chain both when a request spans them
 - **technical-debt-review** — codebase health, hotspots, remediation roadmap
 - **project-review** — whole-project execution health: scope alignment, roadmap adherence, implementation maturity, evidence-it-works
 - **code-archaeology** — understand unfamiliar/legacy code first: history mining, tracing, characterization tests
@@ -180,8 +181,8 @@ When work spans phases, chain skills rather than improvising:
 `brainstorming` (if the idea is still fuzzy) → `feature-planning` →
 `architecture-design` (if structural) → `data-modeling` (if schema) →
 `threat-modeling` (if new trust boundaries) → `plan-execution` (work the
-approved plan; wraps `tdd-workflow` per task) → `code-reviewing` →
-`deployment-checklist`
+approved plan; wraps `tdd-workflow` per task) → `code-slop-cleanup` (strip AI
+artifacts from the diff) → `code-reviewing` → `deployment-checklist`
 
 **Bug / incident**
 `incident-response` (if prod is down) → `bug-investigating` → `tdd-workflow`

package/skills/tdd-workflow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: tdd-workflow
-description: "Guide test-driven development with red-green-refactor. Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD. For NEW code via test-first — use test-suite-design for adding tests to existing code."
+description: "Guide test-driven development with red-green-refactor. For NEW code via test-first — use test-suite-design for adding tests to existing code."
+when_to_use: "Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD."
 allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
 
@@ -138,6 +139,7 @@ These are the excuses that lead to skipping the test. None of them hold up.
 - A new test passes the first time you run it (you never saw RED).
 - You can't explain why the test failed in the RED phase.
 - You're glancing at not-yet-deleted draft code while writing the "test-first" version.
+- You're editing the *test* to make it pass — the test was the spec; change the code, or escalate if the spec itself is wrong.
 
 ## Cross-Skill References
 

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

@@ -25,6 +25,7 @@ Don't try to review everything. Focus on where pain is concentrated.
 - Files changed in almost every PR — high churn indicates poor separation of concerns or missing abstractions
 - Files that always require changes together — tight coupling that should be decoupled
 - Files with frequent bug fixes — instability indicates unclear ownership or poor test coverage
+- AI-assisted bulk commits — large multi-file commits landing at once and revised within days; churn-shortly-after-landing is the strongest slop signal
 
 **Structural signals:**
 - Circular dependencies between modules
@@ -48,9 +49,12 @@ For each hotspot, classify the debt:
 | **Complexity debt** | Functions/classes doing too much | Extract, decompose, simplify |
 | **Duplication debt** | Same logic in multiple places | Extract shared abstraction |
 | **Test debt** | Missing or low-quality tests | Add tests before refactoring anything else |
-| **Documentation debt** | Undocumented non-obvious behavior | Add comments, docstrings, decision records |
+| **Documentation debt** | Undocumented non-obvious behavior (docs *missing*) | Add comments, docstrings, decision records |
+| **Documentation drift** | Docs describing behavior, endpoints, or flags that no longer exist | Fix or delete the stale doc |
 | **Architecture debt** | Wrong abstraction at system level | Restructure, introduce proper boundaries |
 | **Dependency debt** | Outdated, vulnerable, or abandoned libraries | Upgrade or replace |
+| **Type debt** | `any`/casts silencing the checker, single-implementer interfaces "for testing", overly broad types | Restore real types; inline the interface |
+| **Config/scaffolding debt** | Unread config keys/flags, orphan `.env` entries, checked-in generated files, TODO scaffolds | Delete what nothing reads; regenerate instead of committing |
 | **Observability debt** | No logging, metrics, or traceability | Add instrumentation |
 
 **Severity:**
@@ -59,6 +63,19 @@ For each hotspot, classify the debt:
 - **Medium**: Painful but workable. Schedule when capacity allows.
 - **Low**: Noticeable but not impeding. Do it opportunistically when touching related code.
 
+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.
+
+## 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:
+
+- **Evidence or it didn't happen.** Cite `path:line-range` and quote the offending code minimally. No location, no finding.
+- **Argue it, don't label it.** State *why the specific instance is unjustified here* — what it costs and why the pattern lacks a reason that survives scrutiny. "I'd do it differently" is preference, not debt.
+- **Attempt to disprove before flagging.** Trace callers before declaring code dead (dynamic references, string-based lookups, DI, reflection, external consumers); check history before calling a config key unread. If a legitimate reason emerges, downgrade or drop.
+- **Confidence, not assertion.** Unverifiable usage claims get Confidence: Low with a note on what would confirm it — never asserted as fact.
+- **Record what you didn't flag.** An "Explicitly not flagged" section (items considered, reason they survived scrutiny) proves the audit was discerning and stops the team re-litigating.
+- **Log the method.** Tools/passes run with their commands, and anything not covered — unreadable files, missing test env — as named blind spots. If a tool wasn't available, say so; don't fabricate its results.
+
 ## Step 3: Estimate Effort and Risk
 
 For each hotspot, estimate:

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

@@ -11,7 +11,8 @@
         "Categorizes debt by type (complexity, test, architecture, etc.) and severity",
         "Produces a prioritized roadmap with effort estimates",
         "Distinguishes between quick wins, quarterly investments, and strategic changes",
-        "Does not recommend a full rewrite without strong justification"
+        "Does not recommend a full rewrite without strong justification",
+        "States that findings must cite concrete evidence (file/line locations), with unverifiable claims marked low-confidence rather than asserted"
       ]
     },
     {
@@ -22,7 +23,7 @@
         "Recommends focusing on churn (frequently-changed files) rather than trying to address all debt",
         "Emphasizes that test debt must be addressed before structural debt",
         "Provides a concrete prioritization heuristic (not just 'prioritize by impact')",
-        "Acknowledges that low-impact debt can be accepted / deferred",
+        "Acknowledges that low-impact debt can be accepted / deferred (accepted or explicitly-not-flagged items are recorded, not silently dropped)",
         "Does not recommend addressing everything at once"
       ]
     },

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

@@ -29,23 +29,25 @@
 
 ## Debt Inventory
 
+Every inventoried item cites evidence (`path:line-range`) and carries a confidence level — Low confidence means "what would confirm this" is stated in the description, not that the claim is asserted anyway.
+
 ### Critical — Address Immediately
 
-| Item | Type | Location | Description | Effort |
-|------|------|---------|-------------|--------|
-| | | | | |
+| Item | Type | Evidence (path:line) | Description | Confidence | Risk of fix | Effort |
+|------|------|---------------------|-------------|------------|-------------|--------|
+| | | | | | | |
 
 ### High — Schedule This Quarter
 
-| Item | Type | Location | Description | Effort | Prerequisite |
-|------|------|---------|-------------|--------|-------------|
-| | | | | | |
+| Item | Type | Evidence (path:line) | Description | Confidence | Risk of fix | Effort | Prerequisite |
+|------|------|---------------------|-------------|------------|-------------|--------|-------------|
+| | | | | | | | |
 
 ### Medium — Address Opportunistically
 
-| Item | Type | Location | Description |
-|------|------|---------|-------------|
-| | | | |
+| Item | Type | Evidence (path:line) | Description | Confidence |
+|------|------|---------------------|-------------|------------|
+| | | | | |
 
 ### Accepted Debt — Won't Address
 
@@ -53,6 +55,14 @@
 |------|---------------------|
 | | |
 
+### Explicitly Not Flagged
+
+Items considered and deliberately not flagged — proves the audit was discerning and prevents re-litigating.
+
+| Item considered | Why it survived scrutiny |
+|-----------------|--------------------------|
+| | |
+
 ---
 
 ## Remediation Roadmap
@@ -80,6 +90,20 @@
 
 ---
 
+## Method Log
+
+- **Passes run**: [map / static sweep / file-by-file / cross-file / history]
+- **Tools and commands**: [e.g. `npx depcheck`, linter, coverage — with observed output; "not available" if a tool couldn't run — never fabricated]
+- **Not covered → blind spots**: [unreadable files, skipped dirs, missing test env]
+
+---
+
+## Open Questions
+
+[Judgment calls that need user input — e.g. which subsystem matters most, unknown team pain points. Never guessed silently.]
+
+---
+
 ## Next Review Date
 
 [Date — typically 1 quarter from now]

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

@@ -127,6 +127,17 @@ After writing the suite, assess quality (not just line coverage percentage):
 
 Coverage percentage is a floor, not a ceiling. 80% meaningful coverage beats 100% shallow coverage.
 
+## Pruning Test Slop
+
+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
+- **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
+
+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
 
 - **DRY in tests**: Share setup through fixtures/factories, but keep each test readable on its own. A little repetition in tests is better than obscure shared state.