@geminixiang/pi-simplify 0.0.9 → 0.0.10

package/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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.10",
   "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
 
@@ -63,11 +63,21 @@ Before flagging, **search the codebase** (utility directories, shared modules, f
 - **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 +95,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