ux: actionable gap notifications — what happened + what to do

Gap notifications now tell the user:
1. What happened (plain language, not jargon)
2. Why it matters (context about the gap type)
3. What to do next (specific /forge commands)

Before:
  → Document required tools/access in skills or create
    setup-verification skills

After:
  Your agent needed tools or access it doesn't have for
  operations tasks. Check what's missing with /forge gaps,
  then either install the required tool or create a skill
  that documents the setup.

  /forge gaps — full gap details
  /forge behavior_gaps — all behavior patterns

Every gap type (fallback, deferral, uncertainty, infrastructure)
now has domain-specific context and actionable next steps.

Author: Ace Autonomous

index.ts

@@ -376,11 +376,15 @@ function buildPlugin() {
                     msg += `\n\nIt said things like:\n${exLines}`;
                   }
 
-                  // Actionable suggestion
+                  // Actionable suggestion + commands
                   if (g.suggestedAction) {
-                    msg += `\n\n→ ${g.suggestedAction}`;
+                    msg += `\n\n${g.suggestedAction}`;
                   }
 
+                  // Always show next-step commands
+                  msg += `\n\n${mono("/forge gaps")} — full gap details`;
+                  msg += `\n${mono("/forge behavior_gaps")} — all behavior patterns`;
+
                   gapMessages.push(msg);
                 }
 

src/intelligence/proactive-gaps.ts

@@ -228,10 +228,10 @@ export function summarizeBehaviorGaps(): GapSummary[] {
   for (const [key, gapList] of groups) {
     const [domain, gapType] = key.split(":");
     const suggestedActions: Record<string, string> = {
-      fallback: `Create skills for ${domain} to handle tasks the agent currently can't perform`,
-      deferral: `Create proactive skills that execute automatically instead of asking for permission`,
-      uncertainty: `Create skills with explicit verification steps to reduce uncertainty`,
-      infrastructure: `Document required tools/access in skills or create setup-verification skills`,
+      fallback: `Your agent hit a wall on ${domain} tasks — it tried but couldn't complete them. Run /forge gaps to see details, then /forge gap_propose to generate a remediation skill.`,
+      deferral: `Your agent kept asking for permission on ${domain} tasks instead of acting. If you want it to act autonomously, create a skill that grants explicit permission for these operations.`,
+      uncertainty: `Your agent wasn't confident about ${domain} tasks — hedging and second-guessing. A skill with clear verification steps would eliminate the ambiguity.`,
+      infrastructure: `Your agent needed tools or access it doesn't have for ${domain} tasks. Check what's missing with /forge gaps, then either install the required tool or create a skill that documents the setup.`,
     };
 
     summaries.push({