feat: upgrade suggested actions prompt for leverage-first job generation

Rewrite SUGGESTED_ACTIONS_PROMPT to generate 4-6 high-leverage, tiered
actions instead of 2-3 generic ones. Add leverage-first criteria
(outside-in, revenue-adjacent, unknown-before-use, hard-to-do-manually),
demotion rules, output promise requirements, and self-ranking tiers
(hero/primary/secondary). Extend SuggestedActionData with tier and
outputPromise fields with validation.

Author: marian2js

apps/desktop/src/features/dashboard/data/suggested-actions.test.ts

@@ -182,8 +182,8 @@ void test("parseSuggestedActions: accepts conversion and growth categories", ()
 });
 
 void test("SUGGESTED_ACTIONS_PROMPT lists fixed card titles", () => {
-  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("Find launch communities"));
-  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("Draft Product Hunt launch"));
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("Launch on Product Hunt"));
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("Find SEO quick wins"));
 });
 
 // ---------------------------------------------------------------------------
@@ -310,3 +310,99 @@ void test("CATEGORY_TO_SPECIALIST: exports mapping for all 6 categories", () =>
   }
 });
 
+// ---------------------------------------------------------------------------
+// Tier & outputPromise validation
+// ---------------------------------------------------------------------------
+
+void test("parseSuggestedActions: accepts actions with valid tier field", () => {
+  for (const tier of ["hero", "primary", "secondary"]) {
+    const input = JSON.stringify([
+      { id: "tiered", title: "Tiered", promise: "p", description: "d", category: "seo", skills: [], prompt: "pr", tier },
+    ]);
+    const result = parseSuggestedActions(input);
+    assert.equal(result.length, 1, `Should accept tier="${tier}"`);
+    assert.equal((result[0] as Record<string, unknown>).tier, tier);
+  }
+});
+
+void test("parseSuggestedActions: rejects actions with invalid tier value", () => {
+  const input = JSON.stringify([
+    { id: "bad-tier", title: "Bad", promise: "p", description: "d", category: "seo", skills: [], prompt: "pr", tier: "invalid" },
+  ]);
+  const result = parseSuggestedActions(input);
+  assert.equal(result.length, 0);
+});
+
+void test("parseSuggestedActions: accepts actions without tier field (backward compat)", () => {
+  const input = JSON.stringify([
+    { id: "no-tier", title: "No Tier", promise: "p", description: "d", category: "seo", skills: [], prompt: "pr" },
+  ]);
+  const result = parseSuggestedActions(input);
+  assert.equal(result.length, 1);
+  assert.equal(result[0]!.id, "no-tier");
+});
+
+void test("parseSuggestedActions: accepts actions with valid outputPromise field", () => {
+  const input = JSON.stringify([
+    { id: "op", title: "Op", promise: "p", description: "d", category: "seo", skills: [], prompt: "pr", outputPromise: "5 search wedges + page angles" },
+  ]);
+  const result = parseSuggestedActions(input);
+  assert.equal(result.length, 1);
+  assert.equal((result[0] as Record<string, unknown>).outputPromise, "5 search wedges + page angles");
+});
+
+void test("parseSuggestedActions: rejects actions with empty outputPromise string", () => {
+  const input = JSON.stringify([
+    { id: "empty-op", title: "Empty", promise: "p", description: "d", category: "seo", skills: [], prompt: "pr", outputPromise: "" },
+  ]);
+  const result = parseSuggestedActions(input);
+  assert.equal(result.length, 0);
+});
+
+void test("toActionCard: preserves tier and outputPromise when present", () => {
+  const data = {
+    id: "full-card",
+    title: "Full",
+    promise: "p",
+    description: "d",
+    category: "research" as const,
+    skills: ["seo-audit"],
+    prompt: "pr",
+    tier: "hero" as const,
+    outputPromise: "5 search wedges + page angles",
+  };
+  const card = toActionCard(data);
+  assert.equal((card as Record<string, unknown>).tier, "hero");
+  assert.equal((card as Record<string, unknown>).outputPromise, "5 search wedges + page angles");
+});
+
+// ---------------------------------------------------------------------------
+// Updated prompt content assertions
+// ---------------------------------------------------------------------------
+
+void test("SUGGESTED_ACTIONS_PROMPT: requests 4-6 actions", () => {
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("4-6"), "Should request 4-6 actions");
+  assert.ok(!SUGGESTED_ACTIONS_PROMPT.includes("suggest 2-3"), "Should no longer request 2-3 actions");
+});
+
+void test("SUGGESTED_ACTIONS_PROMPT: includes leverage criteria keywords", () => {
+  const lower = SUGGESTED_ACTIONS_PROMPT.toLowerCase();
+  assert.ok(lower.includes("outside-in"), "Should include outside-in");
+  assert.ok(lower.includes("revenue-adjacent"), "Should include revenue-adjacent");
+  assert.ok(lower.includes("unknown-before-use"), "Should include unknown-before-use");
+  assert.ok(lower.includes("hard-to-do-manually"), "Should include hard-to-do-manually");
+});
+
+void test("SUGGESTED_ACTIONS_PROMPT: includes demotion rules", () => {
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.toLowerCase().includes("demote") || SUGGESTED_ACTIONS_PROMPT.toLowerCase().includes("avoid"), "Should include demotion guidance");
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes("internal cleanup") || SUGGESTED_ACTIONS_PROMPT.includes("good hygiene"), "Should mention weak job types to avoid");
+});
+
+void test("SUGGESTED_ACTIONS_PROMPT: includes tier and outputPromise in JSON schema", () => {
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes('"tier"'), "Should include tier field in schema");
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes('"outputPromise"'), "Should include outputPromise field in schema");
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes('"hero"'), "Should mention hero tier");
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes('"primary"'), "Should mention primary tier");
+  assert.ok(SUGGESTED_ACTIONS_PROMPT.includes('"secondary"'), "Should mention secondary tier");
+});
+

apps/desktop/src/features/dashboard/data/suggested-actions.ts

@@ -29,6 +29,10 @@ export interface SuggestedActionData {
   prompt: string;
   /** Short scannable deliverable label, e.g. "3 hero rewrites" */
   outputType?: string;
+  /** Model-assigned tier: hero (1), primary (2-3), or secondary (1-2) */
+  tier?: "hero" | "primary" | "secondary";
+  /** Concrete output promise with quantities, e.g. "5 search wedges + page angles" */
+  outputPromise?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,6 +79,7 @@ export function resolveIcon(category: string): LucideIcon {
 // ---------------------------------------------------------------------------
 
 const VALID_CATEGORIES = new Set<string>(["conversion", "distribution", "growth", "messaging", "research", "seo"]);
+const VALID_TIERS = new Set<string>(["hero", "primary", "secondary"]);
 
 function isValidSuggestedAction(item: unknown): item is SuggestedActionData {
   if (typeof item !== "object" || item === null) return false;
@@ -87,7 +92,9 @@ function isValidSuggestedAction(item: unknown): item is SuggestedActionData {
     typeof obj.category === "string" && VALID_CATEGORIES.has(obj.category) &&
     (obj.skills === undefined || (Array.isArray(obj.skills) && obj.skills.every((s: unknown) => typeof s === "string"))) &&
     typeof obj.prompt === "string" && obj.prompt.length > 0 &&
-    (obj.outputType === undefined || (typeof obj.outputType === "string" && obj.outputType.length > 0))
+    (obj.outputType === undefined || (typeof obj.outputType === "string" && obj.outputType.length > 0)) &&
+    (obj.tier === undefined || (typeof obj.tier === "string" && VALID_TIERS.has(obj.tier))) &&
+    (obj.outputPromise === undefined || (typeof obj.outputPromise === "string" && obj.outputPromise.length > 0))
   );
 }
 
@@ -143,7 +150,7 @@ export function toActionCard(data: SuggestedActionData): ActionCard {
 
 const FIXED_CARD_TITLES = starterActions.map((a) => `- ${a.title}`).join("\n");
 
-export const SUGGESTED_ACTIONS_PROMPT = `You are an expert startup marketing strategist. Your job is to suggest 2-3 highly specific, actionable marketing tasks for this particular business based on the workspace analysis.
+export const SUGGESTED_ACTIONS_PROMPT = `You are an expert startup marketing strategist. Your job is to suggest 4-6 high-leverage, company-specific marketing jobs for this particular business based on the workspace analysis.
 
 Read the workspace context files — PRODUCT.md, MARKET.md, and GROWTH.md — to understand this business deeply.
 
@@ -159,20 +166,44 @@ AVAILABLE SKILL CATALOG — reference these skill IDs in your suggestions:
 - Sales & GTM: revops, sales-enablement, competitor-alternatives
 - Foundation: product-marketing-context
 
-Analyze the workspace context, consider which skills would be most impactful for this business, and suggest 2-3 action cards. Each card should represent a concrete marketing task that produces a specific deliverable.
+LEVERAGE-FIRST GENERATION CRITERIA — prioritize jobs that are:
+- **Outside-in**: discover unknown opportunities about markets, search demand, competitors, channels, proof, or distribution — things the founder cannot see from inside the product
+- **Revenue-adjacent**: tied to acquisition, conversion, trust, or demand generation — not internal cleanup or process work
+- **Unknown-before-use**: reveal something the founder does not already know — the output should surprise, not just confirm
+- **Hard-to-do-manually**: benefit significantly from company context + workflow packaging — not something achievable via a blank ChatGPT prompt
+
+A strong first-run job should meet at least 3 of 4 criteria above.
+
+DEMOTION RULES — avoid leading with these types of jobs:
+- Packaging work the founder already understands (e.g., rewriting copy they wrote)
+- Internal cleanup or "good hygiene" tasks (e.g., meta tag fixes, analytics setup)
+- Generic rewrites achievable via blank chat (e.g., "rewrite homepage hero" without strategic edge)
+- Incremental work that feels like maintenance rather than discovery
+- Jobs whose output the founder could mostly predict before running them
+
+These can appear as secondary jobs but should never dominate the top recommendations.
+
+OUTPUT PROMISE RULES — each job must include a concrete outputPromise with:
+- Specific quantities (e.g., "5", "20", "3-5")
+- Tangible deliverable types (e.g., "search wedges + page angles", "communities + posting angles", "proof pages from product data")
+- Never use abstract terms like "analysis", "strategy help", "growth recommendations", or "workflow result"
+
+TIERING INSTRUCTIONS — self-rank each job:
+- "hero" (exactly 1): the single highest-leverage, most novel job — the best first thing to do for this company. Must feel like discovery, not packaging.
+- "primary" (2-3): strong follow-up jobs that are still high-value and varied across different marketing dimensions
+- "secondary" (1-2): useful concrete jobs that are less essential as first-proof actions — packaging or optimization work lives here
 
 IMPORTANT CONSTRAINTS:
 - The following action cards ALREADY exist. Do NOT suggest duplicates or variations of these:
 ${FIXED_CARD_TITLES}
 - Each suggestion must be DIFFERENT from the above — offer new angles based on what you learned about THIS specific business
-- Titles must imply a concrete result (e.g., "Draft comparison page vs [Competitor]", "Write launch post for r/[specific subreddit]")
+- Titles must imply a concrete result (e.g., "Find 5 search wedges this product can own", "Map 20 communities where ideal users hang out")
 - Do NOT use vague titles like "Improve marketing", "Build strategy", "Optimize funnel"
 - Prompts must reference PRODUCT.md, MARKET.md, and GROWTH.md
 - Categories must be one of: "conversion", "distribution", "growth", "messaging", "research", "seo"
 - Skills must be an array of skill IDs from the catalog above — pick the 1-3 most relevant skills for each action
-- Each suggestion must produce a concrete deliverable
 
-Return ONLY a JSON array with 2-3 objects. No other text, no markdown fences, no explanation.
+Return ONLY a JSON array with 4-6 objects. No other text, no markdown fences, no explanation.
 
 Each object must have these exact fields:
 {
@@ -183,31 +214,73 @@ Each object must have these exact fields:
   "category": "conversion" | "distribution" | "growth" | "messaging" | "research" | "seo",
   "skills": ["skill-id-1", "skill-id-2"],
   "prompt": "Full detailed prompt that will be sent to the AI agent. Must reference PRODUCT.md, MARKET.md, and GROWTH.md workspace files. Must produce a concrete, useful output.",
-  "outputType": "Short deliverable label (under 30 chars) — e.g. '3 hero rewrites', 'Launch copy bundle', 'SEO opportunity map'. Must describe the tangible output the user receives."
+  "outputType": "Short deliverable label (under 30 chars) — e.g. '3 hero rewrites', 'Launch copy bundle', 'SEO opportunity map'",
+  "tier": "hero" | "primary" | "secondary",
+  "outputPromise": "Concrete deliverable with quantities — e.g. '5 search wedges + page angles', '20 communities + posting angles', '5 proof pages from product data'"
 }
 
-EXAMPLES OF GOOD SUGGESTIONS (for a product analytics tool):
+EXAMPLES OF STRONG LEVERAGE-FIRST SUGGESTIONS (for a product analytics tool):
 [
   {
-    "id": "build-referral-program",
-    "title": "Design a referral program",
-    "promise": "Get a complete referral program with incentives, mechanics, and tracking",
-    "description": "Designs a referral program tailored to this product using viral loop mechanics, incentive structures, and tracking setup.",
-    "category": "growth",
-    "skills": ["referral-program"],
-    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Design a complete referral program with incentive structure, viral mechanics, referral flow, tracking setup, and launch plan.",
-    "outputType": "Referral program blueprint"
+    "id": "find-search-wedges",
+    "title": "Find 5 search wedges you can own",
+    "promise": "Discover high-intent search opportunities your competitors are missing",
+    "description": "Analyzes search demand around product analytics pain points, identifies 5 specific keyword wedges where this product can realistically rank, and produces page angles for each wedge.",
+    "category": "seo",
+    "skills": ["seo-audit", "content-strategy"],
+    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Identify 5 specific search wedges this product can own. For each wedge, provide the target keyword cluster, estimated intent, current competitor coverage, and a concrete page angle this product should build.",
+    "outputType": "SEO wedge map",
+    "tier": "hero",
+    "outputPromise": "5 search wedges + page angles with competitor gaps"
   },
   {
-    "id": "draft-comparison-vs-mixpanel",
-    "title": "Draft comparison page vs Mixpanel",
-    "promise": "Create a detailed comparison page highlighting your advantages over Mixpanel",
-    "description": "Analyzes Mixpanel's positioning and creates a comparison page draft that highlights your unique advantages, addresses common switching objections, and targets users searching for alternatives.",
+    "id": "build-proof-pages",
+    "title": "Turn product data into 5 proof pages",
+    "promise": "Convert your product's unique data into trust-building assets",
+    "description": "Identifies 5 proof page opportunities from product data (benchmarks, case patterns, usage insights) and produces outlines that turn internal knowledge into external trust signals.",
+    "category": "conversion",
+    "skills": ["copywriting", "page-cro"],
+    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Identify 5 proof page opportunities where this product's data or usage patterns can be turned into trust-building content. For each, produce a page outline with headline, key data points, and conversion angle.",
+    "outputType": "Proof page bundle",
+    "tier": "primary",
+    "outputPromise": "5 proof page outlines with data angles"
+  },
+  {
+    "id": "map-competitor-comparison-angles",
+    "title": "Generate 5 comparison pages you can win",
+    "promise": "Find the competitor matchups where you have the strongest positioning",
+    "description": "Analyzes the competitive landscape to find 5 specific comparison page opportunities where this product has clear advantages, and drafts positioning angles for each.",
     "category": "messaging",
     "skills": ["competitor-alternatives", "copywriting"],
-    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Then create a detailed comparison page draft of our product vs Mixpanel...",
-    "outputType": "Comparison page draft"
+    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Identify 5 competitor comparison page opportunities. For each, explain why this product wins the matchup, draft the key positioning angles, and outline the page structure.",
+    "outputType": "Comparison page backlog",
+    "tier": "primary",
+    "outputPromise": "5 comparison pages + positioning angles"
+  },
+  {
+    "id": "find-launch-communities",
+    "title": "Map 20 communities where ideal users gather",
+    "promise": "Find the exact online spaces where your target users already hang out",
+    "description": "Discovers 20 online communities (subreddits, Slack groups, Discord servers, forums, newsletters) where this product's ideal users actively discuss relevant problems, with posting angle suggestions.",
+    "category": "distribution",
+    "skills": ["marketing-ideas", "social-content"],
+    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Find 20 specific online communities where this product's ideal users gather. For each community, provide the name, URL, estimated relevance, and 2-3 posting angles tailored to that community's norms.",
+    "outputType": "Community shortlist",
+    "tier": "primary",
+    "outputPromise": "20 communities + posting angles for each"
+  },
+  {
+    "id": "create-outbound-angles",
+    "title": "Draft 4 cold outbound angles + sequences",
+    "promise": "Get ready-to-send outbound sequences targeting your best buyer signals",
+    "description": "Identifies 4 distinct buyer signals for this product and drafts a cold outbound email sequence for each, personalized to the product's positioning and ICP.",
+    "category": "growth",
+    "skills": ["cold-email", "email-sequence"],
+    "prompt": "Read PRODUCT.md, MARKET.md, and GROWTH.md. Identify 4 buyer signals that indicate high purchase intent. For each signal, draft a 3-email cold outbound sequence with subject lines, hooks, and CTAs.",
+    "outputType": "Outbound sequence pack",
+    "tier": "secondary",
+    "outputPromise": "4 outbound angles + 3-email sequences each"
   }
 ]
 
-Now analyze the workspace files and suggest 2-3 actions tailored to THIS business.`;
+Now analyze the workspace files and suggest 4-6 actions tailored to THIS business.`;