@geminixiang/pi-simplify 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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
+
+- Support simplifying specific folders and files as snapshot reviews.
+- Add a preset selector for choosing uncommitted changes or folder snapshot mode.
+
+### Fixed
+
+- Respect configured selection keybindings in simplify TUI selectors.
+- Keep release tags and GitHub release titles v-prefixed.
+
 ## [0.0.8] - 2026-05-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminixiang/pi-simplify",
-  "version": "0.0.8",
+  "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

@@ -1,11 +1,10 @@
-import { getSelectListTheme, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
-  matchesKey,
-  Key,
-  SelectList,
-  wrapTextWithAnsi,
-  type SelectItem,
-} from "@earendil-works/pi-tui";
+  getSelectListTheme,
+  keyHint,
+  rawKeyHint,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey, SelectList, wrapTextWithAnsi, type SelectItem } from "@earendil-works/pi-tui";
 
 import type { Action, SimplifyResult } from "./types.js";
 
@@ -64,7 +63,7 @@ export async function showCandidateSelector(
       Math.min(selectedIndex - Math.floor(maxVisible / 2), selectableItems.length - maxVisible),
     );
 
-  const result = await ctx.ui.custom<SimplifyResult[]>((tui, theme, _keybindings, done) => {
+  const result = await ctx.ui.custom<SimplifyResult[]>((tui, theme, keybindings, done) => {
     const updateListLabel = (index: number) => {
       const item = listItems[index];
       const { candidate } = selectableItems[index];
@@ -82,6 +81,34 @@ export async function showCandidateSelector(
     };
     selectList.onCancel = () => done([]);
 
+    const submitSelection = () => {
+      done(Array.from(selectedSet).map((i) => selectableItems[i].candidate));
+    };
+
+    const cancelSelection = () => {
+      done([]);
+    };
+
+    const toggleCurrent = () => {
+      if (selectedSet.has(cursorPos)) {
+        selectedSet.delete(cursorPos);
+      } else {
+        selectedSet.add(cursorPos);
+      }
+      updateListLabel(cursorPos);
+      tui.requestRender();
+    };
+
+    const toggleAll = () => {
+      if (selectedSet.size === selectableItems.length) {
+        selectedSet.clear();
+      } else {
+        for (let i = 0; i < selectableItems.length; i++) selectedSet.add(i);
+      }
+      updateAllListLabels();
+      tui.requestRender();
+    };
+
     return {
       render(width: number) {
         selectList.setSelectedIndex(cursorPos);
@@ -106,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(
@@ -119,14 +155,23 @@ export async function showCandidateSelector(
           );
           lines.push(theme.fg("muted", `${detailPrefix}Kind: ${current.category}`));
           lines.push(theme.fg("muted", `${detailPrefix}Fix: ${ACTION_LABEL[current.action]}`));
-          lines.push(theme.fg("borderMuted", `${detailIndent}└─ space selects this fix`));
+          lines.push(
+            theme.fg("borderMuted", `${detailIndent}└─ ${rawKeyHint("space", "selects this fix")}`),
+          );
         }
 
         lines.push("");
         lines.push(
           theme.fg(
             "muted",
-            `Selected: ${selectedSet.size} • ↑↓ navigate • space toggle • a select all • enter confirm • esc cancel`,
+            [
+              `Selected: ${selectedSet.size}`,
+              rawKeyHint("↑↓", "navigate"),
+              rawKeyHint("space", "toggle"),
+              rawKeyHint("a", "select all"),
+              keyHint("tui.select.confirm", "confirm"),
+              keyHint("tui.select.cancel", "cancel"),
+            ].join(" • "),
           ),
         );
         return lines;
@@ -135,35 +180,12 @@ export async function showCandidateSelector(
         selectList.invalidate();
       },
       handleInput(data: string) {
-        if (matchesKey(data, Key.enter)) {
-          const results = Array.from(selectedSet).map((i) => selectableItems[i].candidate);
-          done(results);
-          return;
-        }
-        if (matchesKey(data, Key.escape)) {
-          done([]);
-          return;
-        }
-        if (matchesKey(data, Key.space)) {
-          if (selectedSet.has(cursorPos)) {
-            selectedSet.delete(cursorPos);
-          } else {
-            selectedSet.add(cursorPos);
-          }
-          updateListLabel(cursorPos);
-          tui.requestRender();
-          return;
-        }
-        if (matchesKey(data, "a")) {
-          if (selectedSet.size === selectableItems.length) {
-            selectedSet.clear();
-          } else {
-            for (let i = 0; i < selectableItems.length; i++) selectedSet.add(i);
-          }
-          updateAllListLabels();
-          tui.requestRender();
-          return;
-        }
+        if (keybindings.matches(data, "tui.select.confirm")) return submitSelection();
+        if (keybindings.matches(data, "tui.select.cancel")) return cancelSelection();
+
+        // Extra shortcuts: these selector-specific actions are not registered pi keybinding ids.
+        if (matchesKey(data, "space")) return toggleCurrent();
+        if (matchesKey(data, "a")) return toggleAll();
 
         const previousCursorPos = cursorPos;
         selectList.handleInput(data);

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

@@ -1,6 +1,7 @@
 import {
   defineTool,
   DynamicBorder,
+  keyHint,
   type ExtensionAPI,
   type ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
@@ -99,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,
       }),
     ),
@@ -205,7 +220,11 @@ async function showSimplifyTargetSelector(
       selectList.onCancel = () => done(null);
 
       container.addChild(selectList);
-      container.addChild(new Text(theme.fg("dim", "Press enter to confirm or esc to cancel")));
+      container.addChild(
+        new Text(
+          `${keyHint("tui.select.confirm", "confirm")}  ${keyHint("tui.select.cancel", "cancel")}`,
+        ),
+      );
       container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
 
       return {
@@ -247,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