@geminixiang/pi-simplify 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.0.11] - 2026-06-03
+
+### Changed
+
+- Add thin-wrapper review heuristics so `/simplify` flags rename-only wrappers, pass-through factories, single-call-site helpers, duplicated write APIs, and test-only exports only when they create real maintenance cost.
+
+## [0.0.10] - 2026-05-30
+
+### Changed
+
+- Replace each candidate's single `reason` with a three-part cause-and-effect chain — **root issue**, **consequence**, and **benefit after fix** — so findings explain _why_ they matter, not just _what_ to change.
+- Require a real, non-trivial consequence for every finding; items that only make code "slightly shorter" are no longer flagged.
+- Show the full root issue → consequence → benefit chain in the findings selector, and pass the root issue and goal to the apply step.
+
 ## [0.0.9] - 2026-05-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminixiang/pi-simplify",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Simplify: Review changed code for reuse, quality, and efficiency",
   "keywords": [
     "pi-package"

package/prompt.ts

@@ -2,7 +2,7 @@ export const SIMPLIFY_PROMPT = `# Simplify: Review Changed Code for Reuse, Quali
 
 You are a code review assistant. Review the changed code along three axes — **Reuse**, **Quality**, and **Efficiency** — and surface concrete fixes.
 
-Match the user's language for candidate reasons and summaries; if the user's request is in Chinese, write the candidate \`reason\` fields in Chinese.
+Match the user's language for all candidate fields; if the user's request is in Chinese, write the \`rootIssue\`, \`consequence\`, and \`benefit\` fields in Chinese.
 
 ## What to Find
 
@@ -25,8 +25,15 @@ Before flagging, **search the codebase** (utility directories, shared modules, f
 #### B3. Commented-out Code (Review)
 - Old logic left in comments, disabled features, uncustomized templates
 
-#### B4. Over-engineering (Confirm)
+#### B4. Over-engineering / Thin Wrappers (Confirm)
 - Abstractions created "for future use" but unused, single-call-site helpers that should be inlined, useless indirection
+- Thin wrappers that only rename another function or constructor without adding validation, policy, error handling, logging, or a stable public boundary
+- Platform-specific wrapper modules that merely re-export generic session/config helpers under different names
+- Method wrappers on classes that only delegate to a free function already available to callers
+- Test-only exported helpers that can use the real internal/public helper directly instead
+- Small formatting/command helpers whose name repeats a one-line call and have only one call site
+
+**Thin-wrapper discipline:** prefer deleting the wrapper and calling the underlying primitive directly when the wrapper has no independent semantic responsibility. Keep the wrapper if it protects a public API, documents a domain boundary, centralizes cross-cutting behavior, or isolates an unstable dependency.
 
 #### B5. Hacky Patterns (Confirm)
 - **Redundant state**: state that duplicates other state, cached values that could be derived, observers that could be direct calls
@@ -57,17 +64,41 @@ Before flagging, **search the codebase** (utility directories, shared modules, f
    - Assign **category** (reuse / quality / efficiency) and **risk**
    - State the concrete fix (which existing utility to call, which lines to delete, how to parallelize, etc.)
 
+## Thin Wrapper Review Heuristics
+
+When hunting simplification opportunities, explicitly scan for these patterns:
+
+- **Rename-only wrapper:** \`foo()\` only calls \`bar()\` with the same inputs. Inline \`bar()\` unless \`foo\` is a real public/domain concept.
+- **Constructor/factory wrapper:** \`createX(args)\` only returns \`new X(args)\`. Inline construction unless the factory selects implementations or enforces policy.
+- **Scope-specific alias:** \`SlackThing\`/\`ConversationThing\` only wraps a generic helper. Delete it if the generic name is already clear at call sites.
+- **Single-call-site helper:** a helper with one caller and no meaningful name compression. Inline it, especially for one-line formatting, parsing, or path helpers.
+- **Duplicated write APIs:** several \`saveFooConfig\` functions patch different fields in the same file. Consolidate into one \`updateSettings(patch)\`-style API.
+- **Test-only export:** exported solely so tests can call a thin wrapper. Test the underlying public helper or observable behavior instead.
+- **Pass-through class method:** a class method only delegates to a module-level function and is not required by an interface. Remove the method or call the function directly.
+
+Do **not** flag wrappers whose consequence is only "one extra line". Flag them when they create a real maintenance cost: multiple ways to do the same operation, unclear source of truth, misleading domain boundaries, duplicated tests for delegated behavior, or user/developer uncertainty about which API is authoritative.
+
 ## Risk Levels
 
 - **safe**: Definitely apply (dead code, debug remnants)
 - **confirm**: Apply after user confirms (reuse swaps, over-engineering, hacky patterns, efficiency fixes)
 - **review**: User should look first (commented-out code, ambiguous cases)
 
+## Make the Case (REQUIRED for every candidate)
+
+A finding is only useful if it convinces the reader to act. For each candidate, build an explicit cause-and-effect chain across three fields:
+
+1. **rootIssue** — the underlying flaw in the *current* code, not the fix. For reuse, name the existing symbol and file it duplicates. Be specific about what is wrong.
+2. **consequence** — what this flaw *leads to* if left unchanged: divergent implementations that drift, an N+1 query on every request, untested duplicate logic, a memory leak that grows over time, etc.
+3. **benefit** — the concrete advantage after the fix: single source of truth, "-14 lines", "one query instead of N", "covered by existing tests", "no listener leak".
+
+**Discipline:** if you cannot state a real, non-trivial \`consequence\`, do NOT flag the finding. "It's slightly shorter" or "it's a bit cleaner" is not a consequence. Every candidate you return must survive the question *"what actually goes wrong if we leave this?"* — this keeps the list short and every item defensible.
+
 ## Rules
 
 1. When in doubt, mark as "confirm" or "review" — don't change without consent.
-2. For reuse findings, name the existing symbol/file you'd swap to.
-3. For efficiency findings, briefly justify the win (e.g., "N+1 → single query", "sequential awaits → Promise.all").
+2. For reuse findings, name the existing symbol/file you'd swap to in \`rootIssue\`.
+3. For efficiency findings, justify the win in \`benefit\` (e.g., "N+1 → single query", "sequential awaits → Promise.all").
 4. Don't flag necessary code just because it's simple.
 5. Respect existing abstraction boundaries.
 6. Be especially careful with:
@@ -85,7 +116,9 @@ Field notes:
 - \`risk\` — one of: "safe", "confirm", "review"
 - \`file\` — repository-relative path, no backticks, no markdown
 - \`lines\` — line number or range ("42" or "42-57"); empty string if unknown
-- \`reason\` — single plain-text sentence stating the concrete fix
+- \`rootIssue\` — the underlying problem with the current code (for reuse, name the existing symbol + file)
+- \`consequence\` — what goes wrong if left unchanged (no real consequence ⇒ don't flag)
+- \`benefit\` — the concrete advantage gained after the fix
 - \`action\` — one of: "delete", "inline", "refactor", "parallelize"
 
 If there are no candidates, call \`simplify_candidates\` with an empty \`candidates\` array.

package/selector.ts

@@ -133,12 +133,21 @@ export async function showCandidateSelector(
           const detailIndent = "    ";
           const detailPrefix = `${detailIndent}│ `;
           const location = current.lines ? `${current.file}:${current.lines}` : current.file;
-          lines.push(theme.fg("borderMuted", `${detailIndent}┌─ recommendation`));
-          lines.push(
-            ...wrapTextWithAnsi(current.reason, Math.max(1, width - detailPrefix.length)).map(
-              (wrappedLine) => theme.fg("muted", `${detailPrefix}${wrappedLine}`),
-            ),
-          );
+          const wrapWidth = Math.max(1, width - detailPrefix.length);
+
+          const pushSection = (heading: string, body: string) => {
+            if (!body) return;
+            lines.push(theme.fg("borderMuted", `${detailIndent}┌─ ${heading}`));
+            lines.push(
+              ...wrapTextWithAnsi(body, wrapWidth).map((wrappedLine) =>
+                theme.fg("muted", `${detailPrefix}${wrappedLine}`),
+              ),
+            );
+          };
+
+          pushSection("Root issue", current.rootIssue);
+          pushSection("Consequence", current.consequence);
+          pushSection("Benefit after fix", current.benefit);
           lines.push(theme.fg("muted", `${detailPrefix}`));
           lines.push(theme.fg("muted", `${detailPrefix}File: ${location}`));
           lines.push(

package/types.ts

@@ -6,7 +6,12 @@ export type SimplifyResult = {
   category: Category;
   file: string;
   lines: string;
-  reason: string;
+  /** The underlying problem with the current code. */
+  rootIssue: string;
+  /** What this problem leads to if left unchanged. */
+  consequence: string;
+  /** The concrete advantage gained after applying the fix. */
+  benefit: string;
   risk: Risk;
   action: Action;
 };

package/workflow.ts

@@ -100,7 +100,21 @@ function registerSimplifyCandidatesTool(
           pattern: "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$",
         }),
         lines: Type.String({ description: "Line number or range, or empty string if unknown" }),
-        reason: Type.String({ description: "Concrete fix in one sentence" }),
+        rootIssue: Type.String({
+          description:
+            "The root problem with the current code. For reuse, name the existing symbol + file it duplicates. State the underlying flaw, not the fix.",
+          minLength: 1,
+        }),
+        consequence: Type.String({
+          description:
+            "What this problem leads to if left unchanged (e.g. divergent implementations, N+1 queries on every request, untested duplicate logic). If there is no real consequence, do not flag it.",
+          minLength: 1,
+        }),
+        benefit: Type.String({
+          description:
+            "The concrete advantage after applying the fix (e.g. single source of truth, -14 lines, one query instead of N, covered by existing tests).",
+          minLength: 1,
+        }),
         action: actionSchema,
       }),
     ),
@@ -252,7 +266,12 @@ async function applyFindings(
 
 Apply the following findings. Each item includes a bracketed action (e.g. \`[delete]\`, \`[refactor]\`, \`[parallelize]\`, \`[inline]\`) — follow that action, not a blanket delete.
 
-${selected.map((c) => `- ${c.file} (${c.lines || "?"}): ${c.reason} [${c.action}]`).join("\n")}
+${selected
+  .map(
+    (c) =>
+      `- ${c.file} (${c.lines || "?"}) [${c.action}]\n  - Root issue: ${c.rootIssue}\n  - Goal: ${c.benefit}`,
+  )
+  .join("\n")}
 
 For each item:
 1. Read the file to find the exact location