litclaude-ai 0.3.7 → 0.3.8

package/plugins/litclaude/skills/remove-ai-slops/SKILL.md

@@ -1,52 +1,347 @@
 ---
 name: remove-ai-slops
-description: Cleanup workflow for AI-generated bloat, vague wording, fake certainty, overbroad abstractions, and unsupported claims in LitClaude code and docs.
+description: Cleanup workflow for AI-generated bloat, vague wording, fake certainty, overbroad abstractions, and unsupported claims across a bounded set of LitClaude files. Locks behavior with regression/characterization tests FIRST, then runs a categorized, risk-ordered cleanup, then verifies with quality gates and a critical review. Covers 10 slop categories including performance equivalences, needless abstraction, and oversized modules. Use when the user asks to "remove slop", "clean AI code", "deslop", or clean up AI-generated patterns from recent changes.
 ---
 
 # Remove AI Slops
 
 Use this skill when output feels padded, generic, or less precise than the
-system it describes. The cleanup must be behavior-preserving unless paired with
-a test for a behavior change.
+system it describes, OR when a branch's changed files carry AI-generated code
+smells. This is the FULL multi-file cleanup workflow. For a single isolated
+file, use the `ai-slop-remover` alias instead.
 
-## Slop Signals
+The cleanup must be behavior-preserving unless a behavior change is explicitly
+requested and paired with a test for the new behavior.
 
-- Grand claims without an observable command.
-- "Seamless", "robust", or "powerful" without concrete behavior.
-- Repeated caveats in every section.
-- Large abstractions with only one caller.
-- Tests that assert exact prose but not policy.
-- Docs that say a feature exists when the runtime only has guidance.
-- Placeholder-like skills that omit the actual workflow.
+## Central safety invariant: test-first behavior lock
 
-## Cleanup Rules
+**Behavior is locked by green tests BEFORE a single line is removed.** A
+checklist is not safety; a passing regression test is. If you cannot establish a
+green baseline first, you have no safe ground to clean on — STOP and report.
 
-- Replace hype with commands, paths, and expectations.
-- Replace vague "verify it works" with exact test and QA scenario.
-- Delete duplicate warnings once the actionable warning remains.
-- Keep constraints that protect users from publish, destructive commands, and
-  secret exposure.
-- Do not remove useful nuance about Claude Code vs source runtime surfaces.
+This is the one rule that cannot be skipped. Cleaning on uncovered ground is a
+behavior-change time bomb no matter how careful the pass looks.
 
-## LitClaude Hotspots
+## Inputs
 
-Check:
+- **Default scope**: the branch diff versus `merge-base main` (no arguments).
+- **Optional scope**: an explicit file list passed by the caller (e.g. a
+  loop workflow's changed-files set).
 
-- `README.md` and `README_ko-KR.md` for version drift.
-- `docs/hooks.md` for noisy fallback wording.
-- `plugins/litclaude/skills/*/SKILL.md` for shallow placeholders.
-- `plugins/litclaude/commands/*.md` for broken `$ARGUMENTS`.
-- `bin/litclaude-ai.js` for one-off helper bloat.
-- `test/*.test.mjs` for brittle prose pins.
+## Slop categories (what counts as slop)
 
-## Verification
+Ten categories. The first three are stylistic, the next three structural, the
+next two are hidden cost, then behavior coverage, then module size. Each lists
+explicit KEEP versus REFACTOR/REMOVE rules — the KEEP rules are as binding as
+the removals.
 
-Run tests after cleanup. For docs-only cleanup, docs tests are enough for
-automated evidence, but a package dry-run is useful when the README command or
-published package surface changed.
+### Stylistic
 
-## Output Style
+1. **Redundant comments** — comments restating the code, trivial docstrings,
+   section-divider banners, commented-out code, vague `TODO`/`Note` markers.
+   - KEEP: comments explaining WHY (business logic, edge cases, workarounds),
+     ticket/issue links, regex and algorithm explanations.
+   - KEEP: behavior markers used by tests (`# given`, `# when`, `# then`).
+   - REMOVE: comments that only restate WHAT the next line does.
 
-Summarize removed slop by category, not by every sentence. If a section was
-intentionally left verbose because it encodes a workflow, say so.
+2. **Over-defensive guards** — null checks for guaranteed values, try/catch
+   around code that cannot throw, type checks on statically typed params,
+   defaults for required params, backward-compat shims, validation duplicated at
+   multiple layers, broad catch-alls (`except Exception` in Python, empty
+   `catch {}` or `catch (e) { console.error(e) }` without narrowing in
+   TypeScript/JavaScript).
+   - KEEP: validation at system boundaries (user input, external APIs), I/O
+     error handling, nullable persisted fields. A top-level boundary catch-all
+     (CLI `main()`, HTTP handler) with explicit logging plus re-raise is fine.
+   - REFACTOR: broad catch → catch the specific error you expect; empty
+     `catch {}` → narrow with `instanceof` or re-throw.
 
+3. **Excessive complexity** — deep nesting (>3 levels), nested ternaries,
+   boolean expressions combining 4+ predicates, parameter lists over 5 args
+   without a struct/record/object, god functions (>50 lines doing many things),
+   clever one-liners that sacrifice readability, `if/elif` chains discriminating
+   on a type/enum/literal (prefer an exhaustive switch with a never-fallthrough
+   guard).
+   - KEEP: complexity idioms already established in this codebase, intentionally
+     complex hot paths. `if/else` for genuine boolean and range conditions.
+   - REFACTOR: nested if-chains → guard clauses / early returns; complex
+     ternaries → explicit if/else.
+
+### Structural
+
+4. **Needless abstraction / configurability** — pass-through wrappers,
+   single-use helpers, speculative indirection ("we might need this later"),
+   interfaces with one implementer that add no test seam, factory functions that
+   only call a constructor, options/flags nobody requested.
+   - KEEP: abstractions that provide a real seam (testability, multiple
+     implementers, framework-required boundaries).
+
+5. **Boundary violations** — wrong-layer imports (UI reaching into a DB
+   driver), leaky responsibilities (a handler doing service-layer logic), hidden
+   coupling (one module reading another's private state), side effects in
+   pure-named functions.
+   - KEEP: pragmatic short-circuits already established as a pattern here. When
+     unsure, flag for human judgment rather than rewrite.
+
+6. **Dead code** — unused imports, unused private functions/methods, unreachable
+   branches, stale feature flags, debug leftovers (`console.log`, `print(...)`),
+   code referenced nowhere after a removal.
+   - KEEP: code reached via reflection, dynamic dispatch, or string lookup; code
+     intentionally retained as a rollback path (confirm with the user).
+
+### Hidden cost
+
+7. **Duplication** — copy-pasted branches with trivial differences, redundant
+   helpers doing the same thing in two places, repeated magic-number sequences.
+   - KEEP: incidental duplication — two blocks that look alike but serve intents
+     that could diverge. Prefer leaving them separate over forcing a premature
+     shared abstraction.
+
+8. **Performance-equivalent rewrites** — changes provably equivalent in
+   semantics but cheaper in time or space:
+   - O(n²) → O(n) when correctness is preserved (set lookup vs list scan)
+   - repeated computation inside a loop → hoist it out
+   - eager intermediate collections used once → lazy iteration
+   - string concatenation in a loop → join
+   - redundant calls in a loop → batch
+   - `.length`/`len()` recomputed inside a loop → cache it
+   - **Hard rule**: apply only when equivalence is obvious. Do NOT change
+     algorithms with subtle correctness implications and do NOT micro-optimize
+     hot paths without a benchmark. When in doubt, SKIP.
+
+### Behavior coverage
+
+9. **Missing tests** — observable behavior in a changed file that no test pins.
+   The fix is NOT to remove code; it is to ADD the narrowest characterization
+   test that locks current behavior.
+
+### Module size
+
+10. **Oversized modules** — a source file exceeding **250 pure LOC** (non-blank,
+    non-comment lines). This is an architectural defect, not a style preference.
+    Measure pure LOC, then split by responsibility:
+    - identify the distinct responsibilities the file currently owns;
+    - name each new file after the concept it owns — never `utils`, `helpers`,
+      `common`, or numbered shards like `part1`;
+    - present the split plan to the user before executing;
+    - keep any index/re-export file to re-exports only, no logic.
+    - KEEP: a genuinely self-contained single-responsibility script (e.g. a
+      standalone checker). Opt out by saying so and explaining why.
+    - Forbidden escapes: counting blanks/comments toward budget; splitting by
+      token count; catch-all dump files; "it's generated" (only valid for build
+      output); "230 LOC, close enough" — a file about to grow is already over.
+
+## Quality gates
+
+A pass is complete only when every applicable gate is green. Gates genuinely
+N/A for the project are reported as `N/A` with a reason — never silently
+skipped.
+
+| Gate | Tool | Pass condition |
+|---|---|---|
+| Regression/characterization tests | `node --test` or the project's runner via Bash | all green, including any tests added in the behavior-lock phase |
+| Lint | the project's linter via Bash | zero errors (pre-existing warnings OK) |
+| Typecheck | LSP diagnostics on changed files plus the project type-checker | zero new errors on changed files |
+| Unit/integration tests | the project's runner via Bash | all green (pre-existing failures noted, not introduced) |
+| Static/security scan | the project's scanner via Bash | zero new findings, or `N/A` if none configured |
+
+## Process
+
+### Phase 0: Plan
+
+List the phases below as tracked todos and work one at a time.
+
+### Phase 1: Determine scope
+
+If the caller passed file paths, that is the scope. Otherwise compute the branch
+diff with Bash:
+
+```bash
+git diff "$(git merge-base main HEAD)..HEAD" --name-only
+```
+
+Filter out deleted, binary, and generated/vendored files (`node_modules/`,
+`dist/`, `target/`, lockfiles). List the final scope.
+
+For LitClaude specifically, watch these hotspots: `README.md` and
+`README_ko-KR.md` for version drift, `docs/hooks.md` for noisy fallback wording,
+`plugins/litclaude/skills/*/SKILL.md` for shallow placeholders,
+`plugins/litclaude/commands/*.md` for broken `$ARGUMENTS`, `bin/litclaude-ai.js`
+for one-off helper bloat, and `test/*.test.mjs` for brittle prose pins.
+
+### Phase 2: Lock behavior FIRST (non-negotiable)
+
+For each in-scope source file:
+
+1. Identify the observable behavior it exposes (exported functions, HTTP
+   handlers, CLI commands, classes used elsewhere).
+2. Check whether existing tests cover that behavior (`git grep`, project test
+   conventions).
+3. If behavior is uncovered or weakly covered, write the narrowest
+   regression/characterization test that pins CURRENT behavior **before**
+   editing the file. Pin observable outputs, not implementation details.
+4. Run the suite via Bash. It must be **green** before any cleanup begins.
+
+If you cannot establish a green baseline (e.g. the runner is broken), STOP and
+report. Do not clean on unverified ground.
+
+### Phase 3: Cleanup plan
+
+Produce an explicit plan before removing anything:
+
+```
+File: plugins/litclaude/lib/foo.js
+  Categories: dead code, excessive complexity, performance
+  Order: dead code → complexity → performance
+  Risk: medium (touches a caching path)
+
+File: docs/bar.md
+  Categories: redundant comments, over-defensive wording
+  Order: comments → defensive
+  Risk: low
+```
+
+Apply categories in this risk order (safest → riskiest) to minimize the blast
+radius of any single change:
+
+`comments → dead code → defensive bloat → duplication → complexity → abstraction/boundary → performance → missing tests → oversized modules`
+
+### Phase 4: Execute the cleanup
+
+For a small scope, clean the files directly with Edit, one category at a time in
+the risk order above. For a large scope, fan out: dispatch one subagent per file
+with the `Task` tool, each running this same discipline on exactly one file.
+Keep batches bounded (about 5 in flight) so results stay reviewable, and never
+let a subagent touch a file outside its assignment.
+
+Each subagent assignment must be executable: start with `TASK:`, name the exact
+file, the categories to evaluate, the risk order, and the hard constraints
+below; require a `DELIVERABLE` (per-category report with before/after, why-slop,
+why-safe, and reasons for every skip).
+
+Hard constraints for every cleanup, direct or delegated:
+- Behavior MUST be preserved. When equivalence is not obvious, SKIP.
+- Do NOT change public API signatures.
+- Do NOT remove type hints.
+- Do NOT introduce new abstractions or dependencies.
+- Keep the diff minimal and scoped strictly to slop removal.
+- Do NOT touch files outside scope, even if you notice slop in passing — report
+  those under "Remaining risks".
+
+### Phase 5: Verify with quality gates plus critical review
+
+Run all applicable gates, then walk the review checklists.
+
+**Safety**:
+- [ ] No functional logic accidentally removed
+- [ ] All error handling preserved (especially I/O, network, external APIs)
+- [ ] Type hints intact and correct
+- [ ] Imports still valid
+- [ ] No breaking changes to public APIs
+
+**Behavior**:
+- [ ] Return values unchanged (verified by the Phase 2 tests)
+- [ ] Side effects unchanged
+- [ ] Error/exception behavior unchanged
+- [ ] Edge-case handling preserved
+
+**Quality**:
+- [ ] Removed items are genuinely slop, not intentional patterns
+- [ ] Remaining code follows project conventions
+- [ ] No orphaned code or dangling references
+- [ ] Performance rewrites are obviously equivalent (no subtle algorithm shift)
+- [ ] No new abstractions introduced
+
+For a broad, risky, or release-facing scope, run a reviewer pass with a separate
+`Task` subagent in a reviewer role — not a generic worker — to re-walk these
+checklists independently.
+
+### Phase 6: Fix issues
+
+If any gate fails or any checklist item flips:
+
+1. Identify the specific change that caused it and why it broke.
+2. Revert just that hunk (`git checkout` the file or a targeted Edit).
+3. Re-apply only the changes you can prove are safe.
+4. Re-run the failing gate and re-walk the checklist for that file.
+5. Repeat until all gates are green AND the checklists are clean.
+
+If the same file fails three times, STOP and escalate with the file, what you
+tried, what failed, and your hypothesis. Do not keep editing blindly.
+
+## Output report
+
+```text
+AI SLOP REMOVAL REPORT
+======================
+
+Scope: [branch diff vs merge-base main / explicit file list]
+Files: [N files]
+  - path/to/file1.js
+  - path/to/file2.md
+
+Behavior Lock:
+  - Existing coverage: [N files already covered]
+  - Tests added: [M new tests at path/to/test.mjs]
+  - Baseline status: GREEN
+
+Cleanup Plan:
+  - path/to/file1.js: [dead code → complexity → performance]
+  - path/to/file2.md: [comments → defensive]
+
+Per-File Results:
+  path/to/file1.js
+    - Dead code: 3 removed (lines X-Y, A-B, C)
+    - Excessive complexity: 1 simplified (nested ternary → if/else)
+    - Performance: 1 (list scan → set lookup, O(n²)→O(n), behavior identical)
+    - Skipped (preserved): 2 (boundary null check; WHY comment at L88)
+
+Quality Gates:
+  - Regression tests: PASS (N tests, 0 failed)
+  - Lint: PASS
+  - Typecheck (LSP + project): PASS (0 new errors on changed files)
+  - Unit/integration tests: PASS
+  - Static/security scan: N/A (not configured)
+
+Critical Review:
+  - Safety: PASS
+  - Behavior: PASS
+  - Quality: PASS
+
+Issues Found & Fixed:
+  - [None] OR [issue → fix applied]
+
+Remaining Risks / Deferred:
+  - [None] OR [e.g. boundary violation flagged, needs human judgment]
+
+Final Status: CLEAN | ISSUES FIXED | REQUIRES ATTENTION
+```
+
+Summarize removed slop by category, not by every sentence. If a section was left
+intentionally verbose because it encodes a workflow, say so.
+
+## Anti-patterns (do not do these)
+
+- **Skipping Phase 2.** Removing code on uncovered ground is a behavior-change
+  time bomb. The regression test IS the safety mechanism; the checklist
+  complements it, never replaces it.
+- **Bundling unrelated refactors.** Dead-code deletion plus abstraction removal
+  plus a performance change in one commit is impossible to review or bisect.
+- **Algorithm changes disguised as performance.** If equivalence needs a proof,
+  it is a refactor, not a slop fix — put it in a separate change.
+- **Silent skips.** If a gate is N/A, say `N/A` and why. If a check failed and
+  you could not fix it, say so. Never claim PASS without evidence.
+- **Removing WHY comments.** "It's obvious from the code" is rarely true for the
+  next reader. Only remove comments that restate WHAT.
+- **Touching files outside scope.** Report drive-by slop under "Remaining
+  risks" instead of editing it.
+- **Deleting pre-existing dead code you were not asked about.** Flag it; do not
+  remove it as part of an unrelated cleanup.
+
+## When in doubt, SKIP
+
+The default action under any uncertainty is SKIP, not GUESS. A false negative
+(leaving real slop) is recoverable; a false positive (removing load-bearing
+code) breaks the system. Never remove code that serves a functional purpose,
+always verify changes parse and typecheck, and always preserve test coverage by
+adding tests rather than removing them.