Back to Details

slop-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Slop Code Cleanup

冗余代码清理（Slop Code Cleanup）

Aggressively clean up a codebase by eliminating eight distinct categories of code quality problems. Orchestrates eight specialized subagents that each own one cleanup category, so each one stays focused, deep, and fast — and so they can run in parallel on independent slices of the problem.
The philosophy is simple: a clean codebase has one clear way to do each thing. Duplication, weak types, unused code, hidden errors, and legacy fallbacks all create multiple paths where one would do. This skill hunts down those extra paths and removes them.
主动清理代码库，消除八类不同的代码质量问题。该工具会调度八个专门的子代理，每个子代理负责一类清理工作，确保各自专注、深入且高效——它们可以针对问题的独立部分并行运行。
核心理念很简单：整洁的代码库中，每一件事都只有一种清晰的实现方式。重复代码、弱类型、未使用代码、隐藏错误以及遗留回退逻辑都会导致同一功能存在多条实现路径。本工具会找出这些多余路径并将其移除。

Repo Sync Before Edits (mandatory)

编辑前同步仓库（必填）

Before creating/updating/deleting files, sync the current branch with remote:
bash
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"
If the working tree is not clean, stash first, sync, then restore:
bash
git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop
If 
origin
is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.
在创建/更新/删除文件之前，将当前分支与远程仓库同步：
bash
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"
如果工作区未清理，先暂存修改，同步后再恢复：
bash
git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop
如果缺少
origin
远程仓库、无法执行拉取操作，或在变基/暂存时发生冲突，请停止操作并询问用户后再继续。

Safety & Confirmation Gates

安全与确认机制

This skill deletes and rewrites code aggressively. That is the point. But because deletions are harder to reverse than additions, enforce these gates:
  1. Never run on uncommitted changes. If 
    git status
    is not clean, stop and ask the user to commit or stash.
  2. Create a dedicated cleanup branch before any edits (e.g., 
    chore/slop-cleanup-YYYYMMDD
    ). Never work directly on 
    main
    /
    master
    .
  3. One category per commit. Each subagent's changes land in their own commit with a clear message. This makes individual categories revertible without losing the rest.
  4. Test gate between phases. After each subagent completes, run the test suite and typecheck (if available). If tests fail, stop the pipeline and surface the failure — do not continue to the next subagent on a broken tree.
  5. Report before destructive deletion. For subagents that delete code (unused code, legacy, duplicates), surface the deletion list to the user for approval when the deletion count exceeds 50 items or crosses module boundaries.
本工具会主动删除和重写代码，这正是它的核心作用。但由于删除操作比添加操作更难回滚，因此需要遵循以下机制：
  1. 绝不处理未提交的修改。如果
    git status
    显示工作区未清理，请停止操作并要求用户提交或暂存修改。
  2. 创建专门的清理分支后再进行任何编辑（例如：
    chore/slop-cleanup-YYYYMMDD
    ）。绝不要直接在
    main
    /
    master
    分支上操作。
  3. 每个分类对应一次提交。每个子代理的修改会单独提交，并附上清晰的提交信息。这样可以单独回滚某一类修改，而不会影响其他部分。
  4. 阶段之间的测试校验。每个子代理完成工作后，运行测试套件和类型检查（如果可用）。如果测试失败，停止流程并上报失败原因——不要在代码已损坏的情况下继续执行下一个子代理的任务。
  5. 破坏性删除前先汇报。对于负责删除代码的子代理（未使用代码、遗留代码、重复代码），当删除数量超过50项或跨模块删除时，需向用户展示删除列表并获得批准。

Environment Check

环境检查

Before starting:
  1. Detect language/stack — read 
    package.json
    , 
    pyproject.toml
    , 
    go.mod
    , 
    Cargo.toml
    , 
    pom.xml
    , etc. The subagents tailor tool choices (knip, madge, ts-prune, vulture, ruff, etc.) to the stack.
  2. Verify tooling — if a subagent depends on a tool (knip for JS/TS unused code, madge for circular deps), confirm it's installed or can be run via 
    npx
    . If not, fall back to manual analysis and note this in the report.
  3. Determine scope — full codebase vs. a subdirectory. Default to full unless the user specifies.
  4. Detect test/typecheck commands — read scripts in 
    package.json
    , 
    Makefile
    , 
    pyproject.toml
    , CI configs. These run between phases.
开始之前：
  1. 检测语言/技术栈——读取
    package.json
    、
    pyproject.toml
    、
    go.mod
    、
    Cargo.toml
    、
    pom.xml
    等文件。子代理会根据技术栈选择合适的工具（如knip、madge、ts-prune、vulture、ruff等）。
  2. 验证工具可用性——如果某个子代理依赖特定工具（如JS/TS未使用代码检测用knip，循环依赖检测用madge），确认该工具已安装或可通过
    npx
    运行。如果未安装，则 fallback 到手动分析，并在报告中注明。
  3. 确定范围——全代码库还是子目录。默认是全代码库，除非用户指定范围。
  4. 检测测试/类型检查命令——读取
    package.json
    、
    Makefile
    、
    pyproject.toml
    、CI配置中的脚本。这些命令会在阶段之间运行。

Subagent Architecture

子代理架构

Eight specialized subagents, each focused on one cleanup category. They run in two waves because some categories produce findings that others need to reason about. Within a wave, subagents run in parallel.
┌─────────────────────────────────────────────┐
│  Main SKILL (Orchestrator)                  │
│  - Detect stack & tools                     │
│  - Create cleanup branch                    │
│  - Dispatch subagents in waves              │
│  - Run tests between waves                  │
│  - Assemble final report                    │
└──────────────┬──────────────────────────────┘
               │
     ┌─────────┴──────────┐
     │      Wave 1         │  (analyze + narrow edits, run in parallel)
     │                     │
     ▼                     ▼
 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │ Unused   │ │ Circular │ │ Weak     │ │ Slop/    │
 │ Code     │ │ Deps     │ │ Types    │ │ Comments │
 │ (knip)   │ │ (madge)  │ │          │ │          │
 └──────────┘ └──────────┘ └──────────┘ └──────────┘

               ↓ test + typecheck gate ↓

     ┌─────────────────────┐
     │      Wave 2         │  (structural, needs Wave 1 done first)
     │                     │
     ▼                     ▼
 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │ Dedupe/  │ │ Type     │ │ Defensive│ │ Legacy/  │
 │ DRY      │ │ Consol.  │ │ Prog.    │ │ Deprec.  │
 └──────────┘ └──────────┘ └──────────┘ └──────────┘

               ↓ test + typecheck gate ↓

        ┌──────────────────────┐
        │  Report Assembler    │
        │  SLOP_CLEANUP.md     │
        └──────────────────────┘
Why two waves? Wave 1 subagents do pure cleanup — removing things that are clearly wrong. Their results shrink the surface area for Wave 2, which restructures what remains (deduplication, type consolidation, legacy collapse). Running Wave 2 first would mean merging duplicates that later get deleted as unused, wasting work.
八个专门的子代理，每个专注于一类清理工作。它们分为两波运行，因为某些分类的结果会影响其他分类的处理逻辑。同一波内的子代理并行运行。
┌─────────────────────────────────────────────┐
│  主SKILL（编排器）                          │
│  - 检测技术栈与工具                         │
│  - 创建清理分支                             │
│  - 分波调度子代理                           │
│  - 波次之间运行测试                         │
│  - 生成最终报告                             │
└──────────────┬──────────────────────────────┘
               │
     ┌─────────┴──────────┐
     │      第一波         │  (分析 + 精简编辑，并行运行)
     │                     │
     ▼                     ▼
 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │ 未使用代码│ │ 循环依赖 │ │ 弱类型   │ │ 冗余注释 │
 │ 清理器   │ │ 梳理器   │ │ 强化器   │ │ 清理器   │
 │ (knip)   │ │ (madge)  │ │          │ │          │
 └──────────┘ └──────────┘ └──────────┘ └──────────┘

               ↓ 测试 + 类型检查校验 ↓

     ┌─────────────────────┐
     │      第二波         │  (结构性调整，需等待第一波完成)
     │                     │
     ▼                     ▼
 ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
 │ 代码去重/│ │ 类型合并 │ │ 防御性代码│ │ 遗留/废弃│
 │ DRY优化  │ │ 器       │ │ 移除器   │ │ 代码移除器│
 └──────────┘ └──────────┘ └──────────┘ └──────────┘

               ↓ 测试 + 类型检查校验 ↓

        ┌──────────────────────┐
        │  报告生成器          │
        │  SLOP_CLEANUP.md     │
        └──────────────────────┘
**为什么分两波？**第一波的子代理负责纯清理工作——移除明显无用的代码。它们的结果会缩小第二波的处理范围，第二波则负责重构剩余代码（去重、类型合并、遗留代码清理）。如果先运行第二波，可能会合并后续被标记为未使用的重复代码，造成无用功。

Subagent Specifications

子代理规范

Each subagent has its own prompt file in 
agents/
. The orchestrator spawns them via the Agent tool (
subagent_type: general-purpose
) with their prompt file as context.
#WaveSubagentPrompt fileScope
12Deduplicator
agents/deduplicator.md
Extract shared code; apply DRY only where it reduces complexity
22Type Consolidator
agents/type-consolidator.md
Merge duplicate type/interface/struct definitions into shared modules
31Unused Code Killer
agents/unused-code-killer.md
Find and delete unreferenced code using knip/ts-prune/vulture/etc.
41Circular Dep Untangler
agents/circular-dep-untangler.md
Detect and break circular dependencies using madge/dep-cruiser
51Weak Type Strengthener
agents/weak-type-strengthener.md
Replace 
any
/
unknown
/
interface{}
/
Object
with specific types
62Defensive Programming Remover
agents/defensive-programming-remover.md
Remove try/catch, fallbacks, and null-checks that hide errors
72Legacy Code Remover
agents/legacy-code-remover.md
Delete deprecated, fallback, and duplicated-by-migration code paths
81Slop Comment Cleaner
agents/slop-comment-cleaner.md
Remove AI-generated fluff, stubs, work-in-motion comments, LARP
每个子代理在
agents/
目录下有自己的提示文件。编排器通过Agent工具（
subagent_type: general-purpose
）生成子代理，并将其提示文件作为上下文。
序号波次子代理提示文件范围
12代码去重器
agents/deduplicator.md
提取共享代码；仅在能降低复杂度的情况下应用DRY原则
22类型合并器
agents/type-consolidator.md
将重复的类型/接口/结构体定义合并到共享模块
31未使用代码清理器
agents/unused-code-killer.md
使用knip/ts-prune/vulture等工具查找并删除未引用代码
41循环依赖梳理器
agents/circular-dep-untangler.md
使用madge/dep-cruiser检测并打破循环依赖
51弱类型强化器
agents/weak-type-strengthener.md
将
any
/
unknown
/
interface{}
/
Object
替换为具体类型
62防御性代码移除器
agents/defensive-programming-remover.md
移除隐藏错误的try/catch、回退逻辑和空值检查
72遗留代码移除器
agents/legacy-code-remover.md
删除已废弃、回退以及被迁移代码替代的路径
81冗余注释清理器
agents/slop-comment-cleaner.md
移除AI生成的冗余内容、占位符注释、未完成的工作注释以及无意义注释

Orchestration Workflow

编排工作流程

1. Prepare

1. 准备

bash
undefined
bash
undefined

Refuse if working tree is dirty

如果工作区未清理则拒绝执行

git diff-index --quiet HEAD -- || { echo "Commit or stash changes first"; exit 1; }
git diff-index --quiet HEAD -- || { echo "请先提交或暂存修改"; exit 1; }

Create cleanup branch

创建清理分支

date_tag=$(date +%Y%m%d) git checkout -b "chore/slop-cleanup-${date_tag}"

Detect the stack (language, package manager, test command, typecheck command) and write a one-line summary the user sees before dispatch begins.
date_tag=$(date +%Y%m%d) git checkout -b "chore/slop-cleanup-${date_tag}"

检测技术栈（语言、包管理器、测试命令、类型检查命令），并向用户展示一行摘要，然后开始调度。

2. Dispatch Wave 1 in parallel

2. 并行调度第一波

Spawn subagents 3, 4, 5, and 8 in a single turn (multiple Agent tool calls in one message). Each receives:
  • Absolute repo path
  • Stack summary (language, tooling, test command)
  • Instructions to write findings and edits to their own branch area and produce a per-category report at 
    .slop-cleanup/wave-1/<subagent>.md
  • Edit budget: each subagent may edit directly. They must commit their changes with a dedicated message prefixed with their category.
Wait for all four to finish. Run tests and typecheck. If anything broke, stop and report which subagent's commit introduced the failure (bisect by commit).
在同一轮中生成子代理3、4、5、8（在一条消息中调用多个Agent工具）。每个子代理会收到：
  • 仓库绝对路径
  • 技术栈摘要（语言、工具、测试命令）
  • 指令：将发现的问题和编辑内容写入各自的分支区域，并在
    .slop-cleanup/wave-1/<subagent>.md
    生成分类报告
  • 编辑权限：每个子代理可直接编辑代码。它们必须以分类为前缀提交修改，并附上清晰的提交信息。
等待四个子代理全部完成。运行测试和类型检查。如果出现任何错误，停止流程并上报哪个子代理的提交导致了失败（通过提交二分查找）。

3. Dispatch Wave 2 in parallel

3. 并行调度第二波

Spawn subagents 1, 2, 6, and 7. Same protocol — parallel dispatch, per-category reports at 
.slop-cleanup/wave-2/<subagent>.md
, dedicated commits.
Wait for all four to finish. Run tests and typecheck. Stop on failure.
生成子代理1、2、6、7。遵循相同规则——并行调度，分类报告写入
.slop-cleanup/wave-2/<subagent>.md
，单独提交。
等待四个子代理全部完成。运行测试和类型检查。失败则停止。

4. Assemble the final report

4. 生成最终报告

Read each subagent's category report and produce 
SLOP_CLEANUP.md
at the repo root with this structure:
markdown
undefined
读取每个子代理的分类报告，在仓库根目录生成
SLOP_CLEANUP.md
，结构如下：
markdown
undefined

Slop Cleanup Report

冗余代码清理报告

Branch: chore/slop-cleanup-YYYYMMDD Commits: N (list with category and one-line summary) Tests: ✓ passing | Typecheck: ✓ clean
分支： chore/slop-cleanup-YYYYMMDD 提交次数： N （列出分类和一行摘要） 测试： ✓ 通过 | 类型检查： ✓ 无问题

Summary

摘要

  • Files deleted: N
  • Lines removed: N
  • Lines added: N
  • Types consolidated: N
  • Duplicates merged: N
  • Try/catch removed: N
  • Circular deps broken: N
  • Weak types replaced: N
  • Slop comments removed: N
  • 删除文件数：N
  • 移除代码行数：N
  • 添加代码行数：N
  • 合并类型数：N
  • 合并重复代码数：N
  • 移除try/catch数：N
  • 打破循环依赖数：N
  • 替换弱类型数：N
  • 移除冗余注释数：N

By Category

分类详情

1. Unused Code (subagent 3)

1. 未使用代码（子代理3）

...one-line commit summary, then findings table with file/line/what/why...
...一行提交摘要，然后是包含文件/行号/内容/原因的结果表格...

2. Circular Dependencies (subagent 4)

2. 循环依赖（子代理4）

...
...

(etc for all 8 categories)

（其余6个分类同理）

Risk Flags

风险标记

Anything each subagent flagged as "delete at your own risk" (external callers unknown, reflective access, dynamic imports).
各子代理标记为“风险删除”的内容（外部调用者未知、反射访问、动态导入）。

Next Steps

后续步骤

  • Review the branch
  • Run a full regression suite
  • Merge or cherry-pick categories
undefined
  • 审查分支
  • 运行完整回归测试套件
  • 合并或挑选特定分类的修改
undefined

5. Hand off to the user

5. 交付给用户

Show the report path, the branch name, and summarize: "Cleaned up N categories across M files, removed L lines, tests passing on branch X. Review 
SLOP_CLEANUP.md
and merge when ready."
展示报告路径、分支名称，并总结：“已清理M个文件中的N类问题，移除L行代码，分支X测试通过。请查看
SLOP_CLEANUP.md
，准备就绪后即可合并。”

Graceful Degradation

优雅降级

  • No Agent tool available: Run categories sequentially inline. Tell the user this will be slower and offer to narrow scope.
  • Tool missing (e.g., no knip): The affected subagent falls back to grep + manual cross-reference. It notes the degraded mode in its report.
  • Tests fail after a wave: Stop the pipeline. Do not start the next wave. Report which commit broke the build.
  • A subagent returns an empty finding list: That's fine — some codebases really don't have slop in a given category. Record it in the report and move on.
  • Working tree was dirty at start: Refuse and ask the user to commit or stash first.
  • 无Agent工具可用： 按顺序逐个执行分类任务。告知用户这会更慢，并可选择缩小范围。
  • 工具缺失（如无knip）： 受影响的子代理 fallback 到grep + 手动交叉引用。在报告中注明降级模式。
  • 某波次后测试失败： 停止流程。不要开始下一波。上报哪个提交导致构建失败。
  • 子代理返回空结果列表： 没问题——某些代码库可能在特定分类下确实没有冗余代码。在报告中记录并继续。
  • 初始工作区未清理： 拒绝执行，并要求用户先提交或暂存修改。

Writing Style for Edits

编辑风格规范

All subagents share these editing conventions:
  • Prefer deletion over rewriting. If code isn't needed, remove it. Don't "refactor into a cleaner version" what should just be gone.
  • One change per commit within a category. If a subagent makes multiple semantic changes, split them into multiple commits.
  • Explain the why in the commit message, not the code. A commit message can say "Remove fallback for legacy v1 API (removed in #1234)". The code itself doesn't need a comment.
  • Do not add comments to explain the deletion. No 
    // removed legacy handler
    . The git log is the explanation.
  • No backwards-compatibility shims unless the user explicitly asks for them. Clean means clean.
  • Trust the type system and framework guarantees. If a value is declared non-null by a schema, don't add a 
    if (!x) throw
    check.
所有子代理遵循以下编辑约定：
  • 优先删除而非重写。如果代码无用，直接删除。不要重构本应被移除的代码。
  • 同一分类下每次提交对应一个变更。如果子代理进行了多个语义变更，拆分为多个提交。
  • 在提交信息中说明原因，而非代码中。提交信息可以写“移除遗留v1 API的回退逻辑（已在#1234中移除）”。代码本身不需要注释。
  • 不要添加注释说明删除操作。不要写
    // 移除遗留处理器
    。git日志就是说明。
  • 除非用户明确要求，否则不添加向后兼容垫片。清理就是彻底清理。
  • 信任类型系统和框架保证。如果模式声明值为非空，不要添加
    if (!x) throw
    检查。

Step Completion Reports

阶段完成报告

After each wave and at the end, output a status report in this format:
◆ Wave 1 (step 1 of 3 — parallel cleanup)
··································································
  Unused code killer:      √ pass (removed 47 symbols, 12 files)
  Circular dep untangler:  √ pass (broke 3 cycles)
  Weak type strengthener:  √ pass (replaced 89 anys with specific types)
  Slop comment cleaner:    √ pass (removed 234 slop comments)
  Tests after wave:        √ pass
  Typecheck after wave:    √ pass
  ____________________________
  Result:                  PASS
◆ Wave 2 (step 2 of 3 — structural consolidation)
··································································
  Deduplicator:                  √ pass (merged 18 duplicate blocks)
  Type consolidator:             √ pass (moved 23 types to shared/)
  Defensive programming remover: × fail — 3 tests broke, reverted
  Legacy code remover:           √ pass (deleted 2 fallback paths)
  Tests after wave:              × fail — blocked by defensive remover revert
  ____________________________
  Result:                        PARTIAL
◆ Final Report (step 3 of 3 — assembly)
··································································
  SLOP_CLEANUP.md written:   √ pass
  All commits have messages: √ pass
  Branch pushed:             √ pass
  Summary delivered to user: √ pass
  ____________________________
  Result:                    PASS
Use 
√
for pass, 
×
for fail. Keep the adapted check names specific to what actually ran.
每波次结束和最终完成后，按以下格式输出状态报告：
◆ 第一波（第1步/共3步 — 并行清理）
··································································
  未使用代码清理器:      √ 通过（移除47个符号，12个文件）
  循环依赖梳理器:        √ 通过（打破3个循环）
  弱类型强化器:          √ 通过（将89个any替换为具体类型）
  冗余注释清理器:        √ 通过（移除234条冗余注释）
  波次后测试:            √ 通过
  波次后类型检查:        √ 通过
  ____________________________
  结果:                  通过
◆ 第二波（第2步/共3步 — 结构性合并）
··································································
  代码去重器:                  √ 通过（合并18块重复代码）
  类型合并器:                  √ 通过（将23个类型移至shared/）
  防御性代码移除器:            × 失败 — 3个测试损坏，已回滚
  遗留代码移除器:              √ 通过（删除2条回退路径）
  波次后测试:                  × 失败 — 受防御性代码移除器回退影响
  ____________________________
  结果:                      部分完成
◆ 最终报告（第3步/共3步 — 生成）
··································································
  SLOP_CLEANUP.md已生成:   √ 通过
  所有提交均有信息:        √ 通过
  分支已推送:              √ 通过
  摘要已交付用户:          √ 通过
  ____________________________
  结果:                    通过
使用
√
表示通过，
×
表示失败。根据实际运行情况调整检查项名称。