selftune 0.2.15 → 0.2.18

package/cli/selftune/evolution/evolve.ts

@@ -38,6 +38,7 @@ import type {
 } from "../types.js";
 import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import { parseFrontmatter, replaceDescription } from "../utils/frontmatter.js";
+import type { EffortLevel } from "../utils/llm-call.js";
 import { createEvolveTUI } from "../utils/tui.js";
 import { appendAuditEntry } from "./audit.js";
 import { checkConstitution } from "./constitutional.js";
@@ -51,6 +52,8 @@ import {
   selectFromFrontier,
 } from "./pareto.js";
 import { generateMultipleProposals, generateProposal } from "./propose-description.js";
+import { evaluateStoppingCriteria } from "./stopping-criteria.js";
+import { buildUnblockSuggestions } from "./unblock-suggestions.js";
 import type { ValidationResult } from "./validate-proposal.js";
 import {
   TRIGGER_CHECK_BATCH_SIZE,
@@ -79,7 +82,9 @@ export interface EvolveOptions {
   validationModel?: string;
   cheapLoop?: boolean;
   gateModel?: string;
+  gateEffort?: EffortLevel;
   proposalModel?: string;
+  adaptiveGate?: boolean;
   syncFirst?: boolean;
   syncForce?: boolean;
 }
@@ -173,6 +178,73 @@ function formatSimpleDiff(oldText: string, newText: string): string {
   return output.join("\n");
 }
 
+function countValidationLlmCalls(evalSetSize: number): number {
+  if (evalSetSize === 0) return 0;
+  return Math.ceil(evalSetSize / TRIGGER_CHECK_BATCH_SIZE) * 2 * VALIDATION_RUNS;
+}
+
+interface GateDecision {
+  model: string;
+  effort?: EffortLevel;
+  riskSignals: string[];
+}
+
+function countWords(text: string): number {
+  return text
+    .trim()
+    .split(/\s+/)
+    .filter((token) => token.length > 0).length;
+}
+
+function resolveGateDecision(
+  options: EvolveOptions,
+  proposal: EvolutionProposal,
+  validation: ValidationResult,
+  currentDescription: string,
+  confidenceThreshold: number,
+): GateDecision | undefined {
+  const baseModel = options.gateModel;
+  if (!baseModel) return undefined;
+
+  const baseDecision: GateDecision = {
+    model: baseModel,
+    effort: options.gateEffort,
+    riskSignals: [],
+  };
+
+  if (!options.adaptiveGate) return baseDecision;
+
+  const riskSignals: string[] = [];
+  const originalWords = countWords(currentDescription);
+  const proposedWords = countWords(proposal.proposed_description);
+  const wordGrowth = originalWords === 0 ? 1 : proposedWords / originalWords;
+  const lowLift = validation.net_change < 0.15;
+  const hasRegressions = validation.regressions.length > 0;
+  const lowConfidence = proposal.confidence < Math.max(confidenceThreshold + 0.05, 0.75);
+  const broadeningRisk = wordGrowth > 1.8 || proposedWords - originalWords > 32;
+  const notYetStrong = validation.after_pass_rate < 0.9;
+
+  if (hasRegressions) riskSignals.push(`regressions=${validation.regressions.length}`);
+  if (lowLift) riskSignals.push(`low_lift=${validation.net_change.toFixed(3)}`);
+  if (lowConfidence) riskSignals.push(`confidence=${proposal.confidence.toFixed(2)}`);
+  if (broadeningRisk) riskSignals.push(`word_growth=${wordGrowth.toFixed(2)}x`);
+  if (notYetStrong) riskSignals.push(`after_pass_rate=${validation.after_pass_rate.toFixed(2)}`);
+
+  const shouldEscalate = hasRegressions || validation.net_change < 0.1 || riskSignals.length >= 2;
+  if (!shouldEscalate) {
+    return {
+      ...baseDecision,
+      riskSignals,
+    };
+  }
+
+  return {
+    model: "opus",
+    effort: options.gateEffort === "max" ? "max" : "high",
+    riskSignals,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -455,7 +527,7 @@ export async function evolve(
     // -----------------------------------------------------------------------
     // Pareto multi-candidate path
     // -----------------------------------------------------------------------
-    const paretoEnabled = options.paretoEnabled ?? false;
+    const paretoEnabled = options.paretoEnabled ?? true;
     const candidateCount = options.candidateCount ?? 3;
     const tokenEfficiencyEnabled = options.tokenEfficiencyEnabled ?? false;
     const telemetryRecords =
@@ -493,6 +565,7 @@ export async function evolve(
         options.proposalModel,
         aggregateMetrics,
       );
+      llmCallCount += candidateCount;
 
       // Filter by confidence threshold
       const viableCandidates = candidates.filter((c) => c.confidence >= confidenceThreshold);
@@ -563,6 +636,7 @@ export async function evolve(
           agent,
           options.validationModel,
         );
+        llmCallCount += countValidationLlmCalls(evalSet.length);
         recordAudit(
           proposal.proposal_id,
           "validated",
@@ -627,6 +701,7 @@ export async function evolve(
     } else {
       // Standard single-candidate retry loop
       let feedbackReason = "";
+      const previousPassRates: number[] = [];
 
       for (let iteration = 0; iteration < maxIterations; iteration++) {
         iterationsCompleted = iteration + 1;
@@ -680,7 +755,24 @@ export async function evolve(
         );
         if (!constitution.passed) {
           feedbackReason = `Constitutional: ${constitution.violations.join("; ")}`;
-          recordAudit(proposal.proposal_id, "rejected", feedbackReason);
+          // Re-evaluate stopping after a constitutional rejection by treating the
+          // last entry in previousPassRates as the currentPassRate (or 0 on the
+          // first iteration) and slicing it out of history before calling
+          // evaluateStoppingCriteria() with the current iteration/maxIterations,
+          // confidenceThreshold, and proposal.confidence.
+          const constitutionStop = evaluateStoppingCriteria(
+            previousPassRates.at(-1) ?? 0,
+            previousPassRates.slice(0, -1),
+            iteration + 1,
+            maxIterations,
+            confidenceThreshold,
+            proposal.confidence,
+          );
+          recordAudit(
+            proposal.proposal_id,
+            "rejected",
+            `${feedbackReason} (stopping: ${constitutionStop.reason})`,
+          );
           recordEvidence({
             timestamp: new Date().toISOString(),
             proposal_id: proposal.proposal_id,
@@ -690,54 +782,64 @@ export async function evolve(
             stage: "rejected",
             rationale: proposal.rationale,
             confidence: proposal.confidence,
-            details: feedbackReason,
+            details: `${feedbackReason} (stopping: ${constitutionStop.reason})`,
           });
-          if (iteration === maxIterations - 1) {
+          if (constitutionStop.shouldStop) {
             finishTui();
             return withStats({
               proposal: lastProposal,
               validation: null,
               deployed: false,
               auditEntries,
-              reason: feedbackReason,
+              reason: `${feedbackReason} (${constitutionStop.reason})`,
             });
           }
           continue;
         }
 
-        // Step 9: Check confidence threshold
-        if (proposal.confidence < confidenceThreshold) {
-          feedbackReason = `Confidence ${proposal.confidence} below threshold ${confidenceThreshold}`;
-          recordAudit(
-            proposal.proposal_id,
-            "rejected",
-            `Confidence ${proposal.confidence} below threshold ${confidenceThreshold}`,
+        // Step 9: Check confidence threshold via stopping criteria
+        {
+          const preValidationStop = evaluateStoppingCriteria(
+            previousPassRates.at(-1) ?? 0,
+            previousPassRates.slice(0, -1),
+            iteration + 1,
+            maxIterations,
+            confidenceThreshold,
+            proposal.confidence,
           );
-          recordEvidence({
-            timestamp: new Date().toISOString(),
-            proposal_id: proposal.proposal_id,
-            skill_name: skillName,
-            skill_path: skillPath,
-            target: "description",
-            stage: "rejected",
-            rationale: proposal.rationale,
-            confidence: proposal.confidence,
-            details: `Confidence ${proposal.confidence} below threshold ${confidenceThreshold}`,
-          });
-
-          // If this is the last iteration, return early with rejection
-          if (iteration === maxIterations - 1) {
-            finishTui();
-            return withStats({
-              proposal: lastProposal,
-              validation: null,
-              deployed: false,
-              auditEntries,
-              reason: `Confidence ${proposal.confidence} below threshold ${confidenceThreshold}`,
+          if (proposal.confidence < confidenceThreshold) {
+            feedbackReason = `Confidence ${proposal.confidence} below threshold ${confidenceThreshold}`;
+            recordAudit(
+              proposal.proposal_id,
+              "rejected",
+              `${feedbackReason} (stopping: ${preValidationStop.reason})`,
+            );
+            recordEvidence({
+              timestamp: new Date().toISOString(),
+              proposal_id: proposal.proposal_id,
+              skill_name: skillName,
+              skill_path: skillPath,
+              target: "description",
+              stage: "rejected",
+              rationale: proposal.rationale,
+              confidence: proposal.confidence,
+              details: `${feedbackReason} (stopping: ${preValidationStop.reason})`,
             });
-          }
 
-          continue;
+            // Use stopping criteria to decide whether to return or retry
+            if (preValidationStop.shouldStop) {
+              finishTui();
+              return withStats({
+                proposal: lastProposal,
+                validation: null,
+                deployed: false,
+                auditEntries,
+                reason: `${feedbackReason} (${preValidationStop.reason})`,
+              });
+            }
+
+            continue;
+          }
         }
 
         // Step 10: Validate against eval set
@@ -752,7 +854,7 @@ export async function evolve(
           options.validationModel,
         );
         lastValidation = validation;
-        llmCallCount += batchCount * 2 * VALIDATION_RUNS;
+        llmCallCount += countValidationLlmCalls(evalSet.length);
         tui.done(
           `Validation: ${(validation.before_pass_rate * 100).toFixed(1)}% \u2192 ${(validation.after_pass_rate * 100).toFixed(1)}% (improved: ${validation.improved})`,
         );
@@ -791,13 +893,23 @@ export async function evolve(
           },
         });
 
-        // Step 12: Check validation result
+        // Step 12: Evaluate stopping criteria after validation
+        const stopping = evaluateStoppingCriteria(
+          validation.after_pass_rate,
+          previousPassRates,
+          iteration + 1,
+          maxIterations,
+          confidenceThreshold,
+          proposal.confidence,
+        );
+        previousPassRates.push(validation.after_pass_rate);
+
         if (!validation.improved) {
           feedbackReason = `Validation failed: net_change=${validation.net_change.toFixed(3)}, improved=false`;
           recordAudit(
             proposal.proposal_id,
             "rejected",
-            `Validation failed: net_change=${validation.net_change.toFixed(3)}`,
+            `Validation failed: net_change=${validation.net_change.toFixed(3)} (stopping: ${stopping.reason})`,
           );
           recordEvidence({
             timestamp: new Date().toISOString(),
@@ -808,7 +920,7 @@ export async function evolve(
             stage: "rejected",
             rationale: proposal.rationale,
             confidence: proposal.confidence,
-            details: `Validation failed: net_change=${validation.net_change.toFixed(3)}`,
+            details: `Validation failed: net_change=${validation.net_change.toFixed(3)} (stopping: ${stopping.reason})`,
             validation: {
               improved: validation.improved,
               before_pass_rate: validation.before_pass_rate,
@@ -820,21 +932,26 @@ export async function evolve(
             },
           });
 
-          // If this is the last iteration, return with rejection
-          if (iteration === maxIterations - 1) {
+          // Use stopping criteria to decide whether to return or retry
+          if (stopping.shouldStop) {
             finishTui();
             return withStats({
               proposal: lastProposal,
               validation: lastValidation,
               deployed: false,
               auditEntries,
-              reason: `Validation failed after ${maxIterations} iterations: net_change=${validation.net_change.toFixed(3)}`,
+              reason: `Validation failed (${stopping.reason}): net_change=${validation.net_change.toFixed(3)}`,
             });
           }
 
           continue;
         }
 
+        // Validation passed — check if converged or continue
+        if (stopping.shouldStop && stopping.reason.includes("Converged")) {
+          recordAudit(proposal.proposal_id, "validated", `Stopping early: ${stopping.reason}`);
+        }
+
         // Validation passed - break out of retry loop
         break;
       }
@@ -915,18 +1032,39 @@ export async function evolve(
     // -----------------------------------------------------------------------
     let gateValidation: ValidationResult | undefined;
     if (options.gateModel && lastProposal && lastValidation?.improved) {
-      tui.step(`Gate validation (${options.gateModel})...`);
-      gateValidation = await _gateValidateProposal(lastProposal, evalSet, agent, options.gateModel);
-      llmCallCount++;
+      const gateDecision = resolveGateDecision(
+        options,
+        lastProposal,
+        lastValidation,
+        currentDescription,
+        confidenceThreshold,
+      );
+      const gateLabel = gateDecision?.effort
+        ? `${gateDecision.model}, effort=${gateDecision.effort}`
+        : (gateDecision?.model ?? options.gateModel);
+      tui.step(`Gate validation (${gateLabel})...`);
+      gateValidation = await _gateValidateProposal(
+        lastProposal,
+        evalSet,
+        agent,
+        gateDecision?.model ?? options.gateModel,
+        gateDecision?.effort,
+      );
+      llmCallCount += countValidationLlmCalls(evalSet.length);
       tui.done(
-        `Gate (${options.gateModel}): improved=${gateValidation.improved}, net_change=${gateValidation.net_change.toFixed(3)}`,
+        `Gate (${gateLabel}): improved=${gateValidation.improved}, net_change=${gateValidation.net_change.toFixed(3)}`,
       );
 
+      const gatePrefix =
+        gateDecision && gateDecision.riskSignals.length > 0
+          ? `Adaptive gate [${gateDecision.riskSignals.join(", ")}]`
+          : "Gate validation";
+
       if (!gateValidation.improved) {
         recordAudit(
           lastProposal.proposal_id,
           "rejected",
-          `Gate validation failed (${options.gateModel}): net_change=${gateValidation.net_change.toFixed(3)}`,
+          `${gatePrefix} failed (${gateLabel}): net_change=${gateValidation.net_change.toFixed(3)}`,
         );
         recordEvidence({
           timestamp: new Date().toISOString(),
@@ -937,7 +1075,7 @@ export async function evolve(
           stage: "rejected",
           rationale: lastProposal.rationale,
           confidence: lastProposal.confidence,
-          details: `Gate validation failed (${options.gateModel}): net_change=${gateValidation.net_change.toFixed(3)}`,
+          details: `${gatePrefix} failed (${gateLabel}): net_change=${gateValidation.net_change.toFixed(3)}`,
           validation: {
             improved: gateValidation.improved,
             before_pass_rate: gateValidation.before_pass_rate,
@@ -954,7 +1092,7 @@ export async function evolve(
           validation: lastValidation,
           deployed: false,
           auditEntries,
-          reason: `Gate validation failed (${options.gateModel}): net_change=${gateValidation.net_change.toFixed(3)}`,
+          reason: `${gatePrefix} failed (${gateLabel}): net_change=${gateValidation.net_change.toFixed(3)}`,
           gateValidation,
           ...(baselineResult ? { baselineResult } : {}),
         });
@@ -963,7 +1101,7 @@ export async function evolve(
       recordAudit(
         lastProposal.proposal_id,
         "validated",
-        `Gate validation (${options.gateModel}): improved=${gateValidation.improved}, net_change=${gateValidation.net_change.toFixed(3)}`,
+        `${gatePrefix} (${gateLabel}): improved=${gateValidation.improved}, net_change=${gateValidation.net_change.toFixed(3)}`,
       );
     }
 
@@ -1081,7 +1219,7 @@ export async function cliMain(): Promise<void> {
       "dry-run": { type: "boolean", default: false },
       confidence: { type: "string", default: "0.6" },
       "max-iterations": { type: "string", default: "3" },
-      pareto: { type: "boolean", default: false },
+      pareto: { type: "boolean", default: true },
       candidates: { type: "string", default: "3" },
       "token-efficiency": { type: "boolean", default: false },
       "with-baseline": { type: "boolean", default: false },
@@ -1089,7 +1227,9 @@ export async function cliMain(): Promise<void> {
       "cheap-loop": { type: "boolean", default: true },
       "full-model": { type: "boolean", default: false },
       "gate-model": { type: "string" },
+      "gate-effort": { type: "string" },
       "proposal-model": { type: "string" },
+      "adaptive-gate": { type: "boolean", default: false },
       "sync-first": { type: "boolean", default: false },
       "sync-force": { type: "boolean", default: false },
       verbose: { type: "boolean", default: false },
@@ -1120,6 +1260,8 @@ Options:
   --cheap-loop        Use cheap models for loop, expensive for gate (default: on)
   --full-model        Use same model for all stages (disables cheap-loop)
   --gate-model        Model for final gate validation (default: sonnet)
+  --gate-effort       Thinking effort for final gate (low|medium|high|max)
+  --adaptive-gate     Escalate risky gate checks to opus + high effort
   --proposal-model    Model for proposal generation LLM calls
   --sync-first        Refresh source-truth telemetry before building evals/failure patterns
   --sync-force        Force a full rescan during --sync-first
@@ -1142,6 +1284,24 @@ Options:
       "Add --sync-first when using --sync-force",
     );
   }
+  if (values["gate-effort"] && !["low", "medium", "high", "max"].includes(values["gate-effort"])) {
+    throw new CLIError(
+      `Invalid --gate-effort value: ${values["gate-effort"]}`,
+      "INVALID_FLAG",
+      "Use one of: low, medium, high, max",
+    );
+  }
+  if (
+    (values["gate-effort"] || values["adaptive-gate"]) &&
+    (values["full-model"] ?? false) &&
+    !values["gate-model"]
+  ) {
+    throw new CLIError(
+      "--gate-effort and --adaptive-gate require --gate-model when --full-model is set",
+      "INVALID_FLAG",
+      "Add --gate-model <model> or drop --full-model",
+    );
+  }
 
   const { detectAgent } = await import("../utils/llm-call.js");
   const requestedAgent = values.agent;
@@ -1222,6 +1382,8 @@ Options:
     console.error(`[verbose] Dry run: ${values["dry-run"] ?? false}`);
     console.error(`[verbose] Sync first: ${values["sync-first"] ?? false}`);
     console.error(`[verbose] Sync force: ${values["sync-force"] ?? false}`);
+    console.error(`[verbose] Adaptive gate: ${values["adaptive-gate"] ?? false}`);
+    console.error(`[verbose] Gate effort: ${values["gate-effort"] ?? "(default)"}`);
   }
 
   const result = await evolve({
@@ -1240,7 +1402,9 @@ Options:
     validationModel: values["validation-model"],
     cheapLoop: (values["cheap-loop"] ?? true) && !(values["full-model"] ?? false),
     gateModel: values["gate-model"],
+    gateEffort: values["gate-effort"] as EffortLevel | undefined,
     proposalModel: values["proposal-model"],
+    adaptiveGate: values["adaptive-gate"] ?? false,
     gradingResults,
     syncFirst: values["sync-first"] ?? false,
     syncForce: values["sync-force"] ?? false,
@@ -1272,11 +1436,16 @@ Options:
       ...(result.descriptionQualityAfter != null
         ? { description_quality_after: result.descriptionQualityAfter }
         : {}),
+      ...(!result.deployed
+        ? {
+            suggestions: buildUnblockSuggestions(result, values.skill),
+          }
+        : {}),
     };
     console.log(JSON.stringify(summary, null, 2));
   }
 
-  // Print human-readable status to stderr so users always see outcome
+  // Print human-readable status to stderr so agents always see outcome + next steps
   if (!result.deployed) {
     console.error(`\n[NOT DEPLOYED] ${result.reason}`);
     if (result.validation && !result.validation.improved) {
@@ -1295,9 +1464,25 @@ Options:
         `  Confidence ${result.proposal.confidence.toFixed(2)} below threshold ${values.confidence ?? "0.6"}`,
       );
     }
-    console.error("  Re-run with --verbose for full diagnostic output.");
+    // Targeted suggestions based on specific failure reason
+    const suggestions = buildUnblockSuggestions(result, values.skill);
+    if (suggestions.length > 0) {
+      console.error("\n  Next steps:");
+      for (const s of suggestions) {
+        console.error(`    → ${s}`);
+      }
+    }
   } else {
     console.error(`\n[DEPLOYED] ${result.reason}`);
+    // Show quality improvement if available
+    if (result.descriptionQualityBefore != null && result.descriptionQualityAfter != null) {
+      const delta = result.descriptionQualityAfter - result.descriptionQualityBefore;
+      if (delta !== 0) {
+        console.error(
+          `  Description quality: ${Math.round(result.descriptionQualityBefore * 100)}% → ${Math.round(result.descriptionQualityAfter * 100)}% (${delta >= 0 ? "+" : ""}${Math.round(delta * 100)}%)`,
+        );
+      }
+    }
   }
 
   process.exit(result.deployed ? 0 : 1);

package/cli/selftune/evolution/unblock-suggestions.ts

@@ -0,0 +1,159 @@
+/**
+ * unblock-suggestions.ts
+ *
+ * Generates targeted, per-failure-reason suggestions when evolve doesn't deploy.
+ * Each suggestion is a concrete next CLI command or manual action that helps the
+ * agent (or user) unblock the evolution pipeline.
+ *
+ * Pure function — no I/O, no LLM calls. Depends only on EvolveResult fields and
+ * the scoreDescription heuristic.
+ */
+
+import { scoreDescription } from "./description-quality.js";
+import type { EvolveResult } from "./evolve.js";
+
+// ---------------------------------------------------------------------------
+// Quality hint helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Append description quality improvement hints if the score reveals weak criteria.
+ * Only fires when composite < 0.7 to avoid noise on already-good descriptions.
+ * Skips when descriptionText is empty (no proposal was generated).
+ */
+function appendQualityHints(
+  suggestions: string[],
+  descriptionText: string,
+  skillName: string,
+): void {
+  if (!descriptionText) return;
+  const score = scoreDescription(descriptionText, skillName);
+  if (score.composite >= 0.7) return;
+
+  const weak: string[] = [];
+  if (score.criteria.trigger_context < 0.5) weak.push("add when/if/after trigger context");
+  if (score.criteria.vagueness < 0.7) weak.push("remove vague words (various, general, etc)");
+  if (score.criteria.specificity < 0.5) weak.push("add concrete action verbs");
+  if (score.criteria.length < 0.7) weak.push("adjust length (ideal: 80-300 chars)");
+  if (score.criteria.not_just_name < 0.5) weak.push("differentiate from skill name");
+
+  if (weak.length > 0) {
+    suggestions.push(
+      `Description quality: ${Math.round(score.composite * 100)}% — improve by: ${weak.join(", ")}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main suggestion builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate targeted suggestions based on the specific failure reason.
+ * Each suggestion is a concrete next CLI command or manual action.
+ */
+export function buildUnblockSuggestions(result: EvolveResult, skillName: string): string[] {
+  const reason = result.reason;
+  const suggestions: string[] = [];
+  const descText = result.proposal?.original_description ?? "";
+
+  // --- Path/config failures ---
+  if (reason.includes("SKILL.md not found")) {
+    suggestions.push("Verify the --skill-path flag points to a valid SKILL.md file");
+    suggestions.push("Run: selftune init (to re-bootstrap config if paths changed)");
+    return suggestions;
+  }
+
+  if (reason.includes("Failed to load eval set") || reason.includes("not a JSON array")) {
+    suggestions.push("Run: selftune sync (to rebuild source-truth telemetry)");
+    suggestions.push(`Then: selftune evolve --skill ${skillName} (to retry with fresh evals)`);
+    return suggestions;
+  }
+
+  // --- No signal failures ---
+  if (reason.includes("No failure patterns found")) {
+    suggestions.push("This skill may already be routing well — check: selftune status");
+    suggestions.push("If undertriggering, add more sessions so evolve has signal to work with");
+    if (result.descriptionQualityBefore != null && result.descriptionQualityBefore < 0.5) {
+      suggestions.push(
+        `Description quality is ${Math.round(result.descriptionQualityBefore * 100)}% — manually improving the description may help generate patterns`,
+      );
+      appendQualityHints(suggestions, descText, skillName);
+    }
+    return suggestions;
+  }
+
+  // --- Confidence failures (specific before general) ---
+  if (reason.includes("No candidates met confidence")) {
+    suggestions.push(`Lower the threshold: selftune evolve --skill ${skillName} --confidence 0.4`);
+    suggestions.push(
+      `Or increase candidates: selftune evolve --skill ${skillName} --pareto --candidates 5`,
+    );
+    appendQualityHints(suggestions, descText, skillName);
+    return suggestions;
+  }
+  if (reason.toLowerCase().includes("confidence") && reason.includes("threshold")) {
+    suggestions.push(`Lower the threshold: selftune evolve --skill ${skillName} --confidence 0.4`);
+    suggestions.push("Or add more eval entries so the LLM has more context for proposals");
+    appendQualityHints(suggestions, descText, skillName);
+    return suggestions;
+  }
+
+  // --- Validation failures (proposals regressed) ---
+  if (reason.includes("Validation failed after")) {
+    suggestions.push(
+      `The eval set may be contradictory — review with: selftune evolve --skill ${skillName} --verbose`,
+    );
+    suggestions.push(
+      `Try: selftune evolve --skill ${skillName} --pareto --candidates 5 (more diverse proposals)`,
+    );
+    if (result.validation && result.validation.regressions.length > 0) {
+      suggestions.push(
+        `${result.validation.regressions.length} regressions detected — check if negative eval entries are too broad`,
+      );
+    }
+    appendQualityHints(suggestions, descText, skillName);
+    return suggestions;
+  }
+  if (reason.includes("No Pareto candidates improved")) {
+    suggestions.push("All candidates regressed — the eval set may need rebalancing");
+    suggestions.push(`Try: selftune sync --force && selftune evolve --skill ${skillName}`);
+    return suggestions;
+  }
+
+  // --- Gate failures ---
+  if (reason.includes("Baseline gate failed")) {
+    suggestions.push("Improvement was too marginal to justify deployment");
+    suggestions.push("Collect more session data, then retry — small gains compound over time");
+    return suggestions;
+  }
+  if (reason.includes("Gate validation failed")) {
+    suggestions.push("The gate model rejected the proposal — it may be too aggressive");
+    suggestions.push(
+      `Try: selftune evolve --skill ${skillName} --full-model (disables cheap-loop gate)`,
+    );
+    return suggestions;
+  }
+
+  // --- Constitutional rejection ---
+  if (reason.includes("Constitutional")) {
+    suggestions.push("The proposed description violated safety constraints");
+    suggestions.push("Review constitutional rules and manually adjust the description if needed");
+    return suggestions;
+  }
+
+  // --- Dry run (not really a failure) ---
+  if (reason.includes("Dry run")) {
+    suggestions.push(`Deploy: selftune evolve --skill ${skillName} (remove --dry-run to deploy)`);
+    return suggestions;
+  }
+
+  // --- Catch-all for unexpected errors ---
+  if (reason.includes("Error during evolution")) {
+    suggestions.push("Re-run with --verbose for full stack trace");
+    suggestions.push("Run: selftune doctor (to check system health)");
+    return suggestions;
+  }
+
+  return suggestions;
+}