Back to Details

melech-prune

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prune

代码精简（Prune）

After 5–15 prompts of iterative coding with AI, codebases accrete AI residue: orphaned helpers from earlier prompts, dead types, half-migrated state, speculative config keys, and zombie workflows.
The feature works and tests might pass, but the working diff is cluttered with dead pathways and unreferenced scaffolding.
melech-prune
acts as an evidentiary garbage collector and architectural reconciler.
在通过AI进行5-15轮迭代编码后，代码库会积累AI residue：来自早期提示词的孤立辅助函数、无用类型、半迁移状态、推测性配置键以及僵尸工作流。
功能可以正常运行，测试也可能通过，但工作区的差异代码中充斥着无用代码路径和未被引用的脚手架代码。
melech-prune
是一个基于证据的垃圾代码清理工具，同时也是架构协调器。

The Core Philosophy: Inverted Burden of Proof

核心理念：举证责任倒置

In normal coding, developers assume: "The AI wrote this, so it's probably needed."
melech-prune
flips this assumption entirely:
Every added or modified function, type, parameter, state hook, wrapper, and export is assumed GUILTY (dead code, accidental residue, or YAGNI bloat) until proven innocent with concrete evidence.
If a symbol cannot provide proof of reachability and concrete necessity, it is queued for deletion.
在常规编码中，开发者会这样假设："这段代码是AI写的，所以它可能是必要的。"
melech-prune
彻底颠覆了这一假设：
所有新增或修改的函数、类型、参数、state hook、包装器以及导出项都被假定为“有罪”（死代码、意外残留代码或YAGNI冗余代码），除非有具体证据证明其“清白”。
如果某个符号无法提供可访问性和实际必要性的证据，就会被列入删除队列。

The 4 Evidentiary Proofs

四类证据证明

To survive pruning, every symbol in the audited diff must satisfy these four tests:
Proof TypeQuestion AskedEvidentiary RequirementIf Proof Fails
1. Reachability Proof"Can runtime execution actually reach this?"Trace a direct call chain from an active entrypoint (route, UI component, CLI command, export, or event handler).Dead / Zombie Code → Purge.
2. Requirement Proof"Which explicit user requirement demanded this?"Identify the exact user story or bugfix requiring this branch or parameter. If the answer is "in case we need it later", it fails.YAGNI Bloat → Strip.
3. Non-Duplication Proof"Did this logic already exist in the codebase?"Verify whether an existing helper, utility, or standard library method already handles this.Accidental Reinvention → Collapse.
4. Breakage Proof"If we delete this right now, what test or behavior breaks?"Simulate removal or check test coverage. If nothing fails and no behavior shifts, why does it exist?Phantom Scaffolding → Remove.
If a symbol looks like a hand-rolled version of a known library or tool rather than of local code, that is an adoption question and not a deletion — note it and flag it for the user.
要在代码精简中保留下来，审核差异中的每个符号都必须通过以下四项测试：
证据类型提出的问题证据要求未通过的后果
1. Reachability Proof"运行时执行是否真的能到达这里？"追踪从活跃入口点（路由、UI组件、CLI命令、导出项或事件处理器）到该符号的直接调用链。死代码/僵尸代码 → 清除。
2. Requirement Proof"哪一项明确的用户需求要求添加这个？"确定需要该分支或参数的具体用户故事或bug修复。如果答案是“以防以后需要”，则未通过。YAGNI冗余代码 → 移除。
3. Non-Duplication Proof"这段逻辑在代码库中已经存在了吗？"验证现有的辅助函数、工具或标准库方法是否已经实现了该功能。意外重复造轮子 → 合并。
4. Breakage Proof"如果我们现在删除它，哪些测试或行为会被破坏？"模拟删除或检查测试覆盖率。如果没有测试失败，也没有行为变化，那它存在的意义是什么？幻影脚手架代码 → 删除。
如果某个符号看起来是已知库或工具的手动实现版本，而非本地代码的一部分，这属于是否采用的问题，而非删除问题——需将其标记并告知用户。

Workflow

工作流程

text
1. Ask Scope  ──►  2. Build Call Graph  ──►  3. Present Evidence  ──►  4. Ask Approval  ──►  5. Prune & Verify
  (ask_question)     & Run 4 Proofs             Table to User             (ask_question)       (Tests green)
text
1. Ask Scope  ──►  2. Build Call Graph  ──►  3. Present Evidence  ──►  4. Ask Approval  ──►  5. Prune & Verify
  (ask_question)     & Run 4 Proofs             Table to User             (ask_question)       (Tests green)

Step 1: Prompt for Scope

步骤1：确认审核范围

Never assume the diff target. Immediately prompt the user using 
ask_question
to choose the audit boundary:
  • Question: "What scope would you like to prune?"
  • Options: 
    1. (Recommended) Uncommitted working tree (staged + unstaged git diff)
    2. Current branch vs base (git diff origin/main...HEAD or main...HEAD)
    3. Last N commits (e.g. HEAD~3..HEAD)
    4. Specific files or directory (custom path)
If the user passed a specific target in their initial prompt (e.g. 
melech-prune HEAD~2..HEAD
or 
melech-prune src/auth/
), confirm that target directly.
切勿假设差异目标。立即使用
ask_question
提示用户选择审核边界：
  • 问题："你希望精简哪个范围的代码？"
  • 选项: 
    1. (推荐) 未提交的工作区（已暂存+未暂存的git diff）
    2. 当前分支与基准分支对比（git diff origin/main...HEAD 或 main...HEAD）
    3. 最近N次提交（例如 HEAD~3..HEAD）
    4. 特定文件或目录（自定义路径）
如果用户在初始提示中指定了具体目标（例如
melech-prune HEAD~2..HEAD
或
melech-prune src/auth/
），直接确认该目标即可。

Step 2: Audit the Diff with Evidentiary Proofs

步骤2：基于证据证明审核差异代码

Examine every added or modified file in the chosen scope:
  1. Extract all new / modified symbols:
    • Functions, methods, and classes
    • Types, interfaces, DTOs, and enums
    • Imports and exported variables
    • State variables, props, hooks, and event handlers
    • Parameters, flags, and configuration keys
  2. Trace the Call Graph:
    • Trace upwards from leaf helpers to find their callers.
    • Catch Zombie Chains: A helper is NOT alive just because 
      WorkflowA
      calls it, if 
      WorkflowA
      itself has zero callers from the application entrypoints.
  3. Classify Findings into Tiers:
    • 🟢 Tier 1: Undisputed Dead Residue (Zero-risk)
      • Zero-reference local functions, unused imports, orphaned types, unreachable 
        if/else
        branches, dead test fixtures.
    • 🟡 Tier 2: Zombie Workflows & Abandoned Iterations (Medium-risk)
      • Handlers or multi-step logic created in turn 2, abandoned in turn 6 when approach changed, but left wired to phantom state.
    • 🟠 Tier 3: Speculative / YAGNI Bloat (Design-level)
      • Unused options, defensive wrappers with only one trivial caller, over-generalized helper parameters.
    • 🔵 Tier 4: Accidental Duplications
      • Custom helpers written during iteration that reinvent existing codebase utilities.
检查所选范围内的所有新增或修改文件：
  1. 提取所有新增/修改的符号:
    • 函数、方法和类
    • 类型、接口、DTO和枚举
    • 导入和导出变量
    • 状态变量、属性、hooks和事件处理器
    • 参数、标志和配置键
  2. 追踪调用图:
    • 从叶子辅助函数向上追踪，找到它们的调用者。
    • 捕获僵尸调用链：如果
      WorkflowA
      调用了某个辅助函数，但
      WorkflowA
      本身没有来自应用入口点的调用者，那么该辅助函数并不能算作“存活”。
  3. 将发现分类为不同层级:
    • 🟢 层级1：无可争议的死残留代码（零风险）
      • 零引用的本地函数、未使用的导入、孤立类型、不可达的
        if/else
        分支、无用测试夹具。
    • 🟡 层级2：僵尸工作流与废弃迭代代码（中风险）
      • 在第2轮创建的处理器或多步骤逻辑，在第6轮更改方案后被废弃，但仍与幻影状态关联。
    • 🟠 层级3：推测性/YAGNI冗余代码（设计层面）
      • 未使用的选项、只有一个简单调用者的防御性包装器、过度泛化的辅助函数参数。
    • 🔵 层级4：意外重复代码
      • 迭代过程中编写的自定义辅助函数，重复实现了代码库中已有的工具功能。

Step 3: Present Findings & Notification

步骤3：展示发现结果与通知

Before touching any code, output a clear, structured Evidence & Pruning Table:
markdown
undefined
在修改任何代码之前，输出清晰、结构化的证据与精简建议表：
markdown
undefined

🔍 Prune Audit Results (Scope: uncommitted diff)

🔍 Prune Audit Results (Scope: uncommitted diff)

TierFileSymbol / BlockFailed Proof & EvidenceProposed Action
🟢 Tier 1
src/utils/format.ts:L42-L58
formatLegacyDate()
Reachability: 0 call sites across repo.Delete function
🟢 Tier 1
src/types/user.ts:L12
LegacyUserRole
Reachability: Unreferenced type.Delete enum variant
🟡 Tier 2
src/hooks/useCart.ts:L85-L102
syncToLocalStorage()
Breakage: Added in turn 3, superseded by IndexedDB in turn 7. Only called by unused draft handler.Delete handler & state
🟠 Tier 3
src/services/api.ts:L30
options.retryDelay
Requirement: YAGNI; hardcoded to default everywhere, no callers supply custom delay.Inline & simplify

---
TierFileSymbol / BlockFailed Proof & EvidenceProposed Action
🟢 Tier 1
src/utils/format.ts:L42-L58
formatLegacyDate()
Reachability: 0 call sites across repo.Delete function
🟢 Tier 1
src/types/user.ts:L12
LegacyUserRole
Reachability: Unreferenced type.Delete enum variant
🟡 Tier 2
src/hooks/useCart.ts:L85-L102
syncToLocalStorage()
Breakage: Added in turn 3, superseded by IndexedDB in turn 7. Only called by unused draft handler.Delete handler & state
🟠 Tier 3
src/services/api.ts:L30
options.retryDelay
Requirement: YAGNI; hardcoded to default everywhere, no callers supply custom delay.Inline & simplify

---

Step 4: Request Explicit User Approval

步骤4：请求用户明确批准

Never prune without human sign-off.
Use 
ask_question
to request the user's verdict:
  • Question: "How would you like to proceed with the pruning recommendations?"
  • Options: 
    1. (Recommended) Prune all verified items (Tiers 1, 2, 3, and 4)
    2. Prune only Tier 1 (Zero-risk dead code & unreferenced symbols)
    3. Let me specify which items to keep or prune
    4. Cancel (Keep working tree unchanged)
If the user picks Option 3, ask which specific items from the table they want to preserve before proceeding.
未经人工确认，切勿进行代码精简。
使用
ask_question
请求用户的决定：
  • 问题："你希望如何处理这些精简建议？"
  • 选项: 
    1. (推荐) 精简所有已验证项（层级1、2、3和4）
    2. 仅精简层级1（零风险死代码和未引用符号）
    3. 让我指定要保留或精简的具体项
    4. 取消（保持工作区不变）
如果用户选择选项3，在继续操作前询问他们希望保留表中的哪些具体项。

Step 5: Surgical Pruning & Verification

步骤5：精准精简与验证

Once approved:
  1. Delete Dead Code: Remove the approved functions, types, branches, and parameters.
  2. Clean Up Dangling References: Remove unused imports and unneeded variables left behind by deletions.
  3. Respect Comments: Preserve load-bearing landmine/WHY comments, and remove comments only if the code they explain was deleted.
  4. Run Verification:
    • Run the test suite (
      npm test
      , 
      pytest
      , 
      cargo test
      , 
      go test
      , etc.).
    • Run type checking (
      tsc
      , 
      mypy
      , 
      cargo check
      , etc.) or build commands.
    • If any test fails, inspect whether a test was testing a deleted dead path (update test) or if an unintended dependency was touched (revert & fix).
  5. Summarize Outcome:
    • Lines of code removed
    • Files cleaned
    • Final verification/test status (e.g. 
      All 42 tests passing green
      )
获得批准后：
  1. 删除死代码：移除已批准的函数、类型、分支和参数。
  2. 清理悬空引用：移除删除操作留下的未使用导入和不必要变量。
  3. 尊重注释：保留关键的landmine/WHY注释，仅当注释所解释的代码被删除时才移除该注释。
  4. 运行验证:
    • 运行测试套件（
      npm test
      , 
      pytest
      , 
      cargo test
      , 
      go test
      , etc.）。
    • 运行类型检查（
      tsc
      , 
      mypy
      , 
      cargo check
      , etc.）或构建命令。
    • 如果有测试失败，检查是否是测试了已删除的死代码路径（更新测试），或者是否意外触及了未预期的依赖（回滚并修复）。
  5. 总结结果:
    • 移除的代码行数
    • 清理的文件数量
    • 最终验证/测试状态（例如
      All 42 tests passing green
      ）

Do / Don't

注意事项（Do / Don't）

Do: Prompt for the audit scope with 
ask_question
before running the analysis.
Don't: Guess the git diff target without confirming.
Do: Provide concrete proof (e.g. "0 references in repo", "only caller is dead function X") for every item flagged.
Don't: Say "this looks unnecessary" without showing the call graph evidence.
Do: Require explicit user approval via 
ask_question
before deleting files or code blocks.
Don't: Silently delete code behind the scenes.
Do: Run tests and type checks immediately after pruning to prove the build remains green.
Don't: Leave broken imports or failing test suites after a cleanup.
需要做： 在运行分析前，使用
ask_question
提示用户确认审核范围。
不要做： 在未确认的情况下猜测git diff目标。
需要做： 为每个标记的项提供具体证据（例如*"0 references in repo", "only caller is dead function X"）。
不要做： 在未展示调用图证据的情况下说"this looks unnecessary"*。
需要做： 在删除文件或代码块前，通过
ask_question
获得用户明确批准。
不要做： 在后台静默删除代码。
需要做： 精简完成后立即运行测试和类型检查，证明构建仍能正常通过。
不要做： 清理后留下损坏的导入或失败的测试套件。