@recapt/mcp 0.0.13-beta → 0.0.15-beta

package/skills/self-healing.md

@@ -1,13 +1,131 @@
 # Recapt Self-Healing Workflow
 
-Use this workflow when asked to "fix issues", "heal the site", or improve UX based on behavioral data from recapt.
+Use this workflow when asked to "heal the site" or improve UX based on behavioral data from recapt.
 
 ## When to Use
 
-- User asks to fix UX issues or friction points
-- User wants to improve conversion or reduce drop-offs
-- User asks to "heal" or "diagnose" their site
-- After identifying issues with `run_full_diagnostic`
+This is a **comprehensive site improvement workflow**. Only use it when the user explicitly requests a full-site analysis:
+
+- "Heal my site"
+- "Run the self-healing workflow"
+- "Analyze my whole site and improve it"
+- "Do a full UX audit"
+- "Make general improvements across the site"
+  **Do NOT use this workflow for:**
+- Specific page fixes ("fix the checkout button")
+- Single flow optimization ("improve the signup funnel")
+- Investigating a specific issue ("why are users rage clicking here?")
+  For specific requests, use the appropriate tools directly — let the conversation guide which tools to call.
+
+## Run Tracking
+
+At the start of each healing session, register the run to track progress and outcomes:
+
+- Search: "healing run" → `start_healing_run`, `update_healing_run`, `record_healing_action`
+
+```
+const response = await start_healing_run({
+  trigger_type: "manual",  // or "github_actions", "cron", "api"
+  trigger_metadata: { ... },  // optional: branch, actor, etc.
+  phases: [
+    { name: "diagnose", status: "pending" },
+    { name: "investigate", status: "pending" },
+    { name: "fix", status: "pending" },
+    { name: "track", status: "pending" }
+  ]
+})
+
+// IMPORTANT: Extract the run ID from the response
+const run_id = response.id;  // e.g., "682d1a2b3c4d5e6f7a8b9c0d"
+```
+
+This creates a run record visible in the Healing Runs UI. **You must update the run as you progress through each phase.**
+
+### Phase Progress Updates
+
+Update the run status at each phase transition. Always pass the complete phases array with updated statuses:
+
+**After starting diagnose:**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  phases: [
+    { name: "diagnose", status: "running", startedAt: new Date().toISOString() },
+    { name: "investigate", status: "pending" },
+    { name: "fix", status: "pending" },
+    { name: "track", status: "pending" }
+  ]
+})
+```
+
+**After completing diagnose (before investigate):**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  phases: [
+    { name: "diagnose", status: "completed", completedAt: new Date().toISOString(), output: { issuesFound: 5, opportunitiesFound: 3 } },
+    { name: "investigate", status: "running", startedAt: new Date().toISOString() },
+    { name: "fix", status: "pending" },
+    { name: "track", status: "pending" }
+  ],
+  summary: { issuesFound: 5 }
+})
+```
+
+**After completing investigate (before fix):**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  phases: [
+    { name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
+    { name: "investigate", status: "completed", completedAt: new Date().toISOString(), output: { issuesInvestigated: 5, issuesValidated: 4 } },
+    { name: "fix", status: "running", startedAt: new Date().toISOString() },
+    { name: "track", status: "pending" }
+  ]
+})
+```
+
+**After completing fix (before track):**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  phases: [
+    { name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
+    { name: "investigate", status: "completed", completedAt: "...", output: { ... } },
+    { name: "fix", status: "completed", completedAt: new Date().toISOString(), output: { fixesApplied: 3, prsCreated: 2 } },
+    { name: "track", status: "running", startedAt: new Date().toISOString() }
+  ],
+  summary: { issuesFound: 5, issuesFixed: 3, prsCreated: 2 }
+})
+```
+
+**After completing track (run complete):**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  status: "completed",
+  completed_at: new Date().toISOString(),
+  duration_ms: <elapsed_time>,
+  phases: [
+    { name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
+    { name: "investigate", status: "completed", completedAt: "...", output: { ... } },
+    { name: "fix", status: "completed", completedAt: "...", output: { ... } },
+    { name: "track", status: "completed", completedAt: new Date().toISOString(), output: { deploymentsConfirmed: 2 } }
+  ],
+  summary: {
+    issuesFound: 5,
+    issuesFixed: 3,
+    issuesDeferred: 1,
+    issuesDismissed: 1,
+    prsCreated: 2
+  }
+})
+```
 
 ## Workflow
 
@@ -33,42 +151,173 @@ If fixes have sufficient data:
 
 ### 1. Diagnose
 
+**Update phase status to "running" before starting.**
+
 Start with `run_full_diagnostic` (always available) to get a prioritized list of issues across the site.
 
-### 2. Investigate
+After diagnosis completes, **update the phase to "completed"** and set `summary.issuesFound`.
+
+### 2. Analyze Flows
+
+After diagnosing issues, proactively look for flow optimization opportunities — even when nothing is "broken."
+
+#### 2a. Discover Journey Patterns
+
+- Search: "journey patterns" → `get_journey_patterns`
+- Look for:
+  - **Backtrack hotspots** — pages users return to repeatedly (signals confusion or missing information)
+  - **Dropoff pages** — where sessions end unexpectedly (potential conversion leaks)
+  - **Unexpected paths** — users taking roundabout routes to reach goals
+
+#### 2b. Analyze Key Funnels
+
+- Search: "analyze funnel" → `analyze_funnel`
+- Analyze critical conversion paths:
+  - Landing → Signup/Trial
+  - Pricing → Checkout → Success
+  - Onboarding flows
+- For each funnel step, note:
+  - Dropoff rate (>30% is a red flag)
+  - Frustration/confusion scores
+  - Dwell time anomalies
+
+#### 2c. Analyze Specific Flows
+
+- Search: "analyze flow" → `analyze_flow`, `get_flow_friction`
+- For pages with high dropoff or backtracking, analyze the flow in detail:
+  - What's the success rate for users entering this flow?
+  - Where are the bottlenecks?
+  - What's the friction score at each step?
+
+#### 2d. Understand User Segments
+
+- Search: "personas" → `discover_personas`
+- Identify behavioral personas:
+  - Which personas struggle most?
+  - What are their risk factors?
+  - What interventions are recommended?
+
+#### 2e. Compare Success vs Failure
+
+- Search: "compare cohorts" → `compare_cohorts`
+- For flows with low conversion, compare:
+  - Users who completed vs dropped off
+  - Users on mobile vs desktop
+  - New vs returning users
+- Look for patterns: What do successful users do differently?
+
+#### Presenting Flow Opportunities
 
-For each high-priority issue, search for investigation tools:
+Present opportunities alongside issues, clearly labeled:
+
+> **Issues Found:**
+>
+> 1. [CRITICAL] Rage clicks on checkout button — JS error
+> 2. [HIGH] Dead clicks on pricing toggle
+>
+> **Flow Optimization Opportunities:**
+>
+> 1. [OPPORTUNITY] 40% backtrack from /pricing to /features — consider adding feature comparison on pricing page
+> 2. [OPPORTUNITY] 65% dropoff at step 2 of onboarding — simplify or add progress indicator
+> 3. [OPPORTUNITY] Mobile users 3x more likely to abandon checkout — review mobile UX
+
+### 3. Investigate
+
+**Update phase status: mark "diagnose" as completed, "investigate" as running.**
+
+For each high-priority issue or opportunity, search for investigation tools:
 
 - Search: "investigate issue" → `investigate_issue`, `validate_issue`
 - This provides detailed context: affected sessions, element interactions, timing patterns
 
-### 3. Triage
+For flow opportunities, also consider:
+
+- Watching session replays of users who dropped off vs completed
+- Checking element friction on high-dropoff pages
+
+### 4. Triage
 
 Present findings to the user. Not all detected issues need fixing:
 
 - Search: "dismiss issue" → `dismiss_issue`, `mark_intended_behavior`
 - Some behaviors are intentional (e.g., rage clicks on a "copy" button)
-- Ask the user which issues to address before proceeding
+- Some flow patterns may be acceptable (e.g., users comparing options before deciding)
+- Ask the user which issues and opportunities to address before proceeding
+
+**After triage, update phase status: mark "investigate" as completed, "fix" as running.**
 
-### 4. Fix
+### 5. Fix
 
-Implement code changes to address the issues. After making changes:
+Implement code changes to address issues and opportunities. After making changes:
 
 - Search: "propose fix" → `propose_fix`, `get_similar_fixes`, `get_fix_history`
 - Log the remediation so recapt can track its effectiveness
 
-### 5. Track
+**Note:** `propose_fix` accepts either `issue_id` (for formal issues) or `page_path` + `element_selector` (for element friction fixes without a formal issue).
+
+**Record each action in the healing run:**
+
+```
+record_healing_action({
+  run_id: "<run_id>",
+  issue_id: "<issue_id>",  // optional - omit for element friction fixes
+  action_type: "code_fix",  // or "needs_more_data", "dismissed", "marked_intended"
+  hypothesis: "The checkout button is unresponsive due to a JS error...",
+  expected_improvement: "Fixing the error handler should reduce rage clicks by 50%",
+  code_changes: [{ file: "checkout.tsx", diff: "...", linesAdded: 5, linesRemoved: 2 }],
+  pr_url: "https://github.com/...",
+  pr_number: 123,
+  remediation_id: "<remediation_id>"  // from propose_fix response.id
+})
+```
+
+For flow optimizations, common fixes include:
+
+- Adding missing information to reduce backtracking
+- Simplifying forms to reduce abandonment
+- Adding progress indicators to multi-step flows
+- Improving CTAs and visual hierarchy
+- Adding social proof or trust signals at decision points
+
+### 6. Track
+
+**Update phase status: mark "fix" as completed, "track" as running.**
 
 Mark fixes as deployed so recapt can measure impact:
 
 - Search: "deployment" → `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`
 
-### 6. Learn
+**Complete the healing run when done:**
+
+```
+update_healing_run({
+  run_id: "<run_id>",
+  status: "completed",
+  completed_at: new Date().toISOString(),
+  duration_ms: <elapsed_time>,
+  phases: [
+    { name: "diagnose", status: "completed", ... },
+    { name: "investigate", status: "completed", ... },
+    { name: "fix", status: "completed", ... },
+    { name: "track", status: "completed", completedAt: new Date().toISOString() }
+  ],
+  summary: {
+    issuesFound: 5,
+    issuesFixed: 3,
+    issuesDeferred: 1,
+    issuesDismissed: 1,
+    prsCreated: 2
+  }
+})
+```
+
+### 7. Learn
 
 Build site knowledge for future reference:
 
 - Search: "site knowledge" → `get_site_knowledge`, `add_site_knowledge`
 - Document patterns, intended behaviors, and architectural decisions
+- Record successful flow optimizations for future reference
 
 ## Post-Fix Behavior
 
@@ -84,12 +333,78 @@ If the user agrees:
 
 ## Tool Discovery Reference
 
-| Phase         | Search Query        | Tools                                                      |
-| ------------- | ------------------- | ---------------------------------------------------------- |
-| Check Pending | "pending fixes"     | `list_pending_fixes`, `evaluate_fix`                       |
-| Diagnose      | (always available)  | `run_full_diagnostic`                                      |
-| Investigate   | "investigate issue" | `investigate_issue`, `validate_issue`                      |
-| Triage        | "dismiss issue"     | `dismiss_issue`, `mark_intended_behavior`                  |
-| Fix           | "propose fix"       | `propose_fix`, `get_similar_fixes`, `get_fix_history`      |
-| Track         | "deployment"        | `confirm_deployment`, `evaluate_fix`, `list_pending_fixes` |
-| Learn         | "site knowledge"    | `get_site_knowledge`, `add_site_knowledge`                 |
+| Phase         | Search Query        | Tools                                                                                   |
+| ------------- | ------------------- | --------------------------------------------------------------------------------------- |
+| Run Tracking  | "healing run"       | `start_healing_run`, `update_healing_run`, `record_healing_action`, `list_healing_runs` |
+| Check Pending | "pending fixes"     | `list_pending_fixes`, `evaluate_fix`                                                    |
+| Diagnose      | (always available)  | `run_full_diagnostic`                                                                   |
+| Journey       | "journey patterns"  | `get_journey_patterns`                                                                  |
+| Funnels       | "analyze funnel"    | `analyze_funnel`                                                                        |
+| Flows         | "analyze flow"      | `analyze_flow`, `get_flow_friction`                                                     |
+| Personas      | "personas"          | `discover_personas`                                                                     |
+| Compare       | "compare cohorts"   | `compare_cohorts`                                                                       |
+| Investigate   | "investigate issue" | `investigate_issue`, `validate_issue`                                                   |
+| Triage        | "dismiss issue"     | `dismiss_issue`, `mark_intended_behavior`                                               |
+| Fix           | "propose fix"       | `propose_fix`, `get_similar_fixes`, `get_fix_history`                                   |
+| Track         | "deployment"        | `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`                              |
+| Learn         | "site knowledge"    | `get_site_knowledge`, `add_site_knowledge`                                              |
+
+## Response Formats
+
+Healing run tools return objects with an `id` field. Extract and store these IDs for subsequent calls.
+
+**Note:** Response formats for `propose_fix` and `add_site_knowledge` are documented in their tool descriptions (discoverable via `search_tools`).
+
+### start_healing_run
+
+```json
+{
+  "id": "682d1a2b3c4d5e6f7a8b9c0d",
+  "status": "running",
+  "trigger": { "type": "manual", "metadata": {} },
+  "phases": [
+    {
+      "name": "diagnose",
+      "status": "pending",
+      "startedAt": null,
+      "completedAt": null,
+      "output": {}
+    }
+  ],
+  "summary": {
+    "issuesFound": 0,
+    "issuesFixed": 0,
+    "issuesDeferred": 0,
+    "issuesDismissed": 0,
+    "prsCreated": 0
+  },
+  "startedAt": "2026-04-26T19:00:00.000Z",
+  "completedAt": null,
+  "durationMs": null,
+  "createdAt": "2026-04-26T19:00:00.000Z"
+}
+```
+
+**Extract:** `response.id` → use as `run_id` in `update_healing_run` and `record_healing_action`
+
+### record_healing_action
+
+```json
+{
+  "id": "682d1a2b3c4d5e6f7a8b9c11",
+  "healingRunId": "682d1a2b3c4d5e6f7a8b9c0d",
+  "issueId": "682d1a2b3c4d5e6f7a8b9c0f",
+  "actionType": "code_fix",
+  "outcome": {
+    "hypothesis": "...",
+    "expectedImprovement": "...",
+    "codeChanges": [...],
+    "prUrl": "https://github.com/...",
+    "prNumber": 123
+  },
+  "remediationId": "682d1a2b3c4d5e6f7a8b9c0e",
+  "createdAt": "2026-04-26T19:45:00.000Z"
+}
+```
+
+**Note:** This automatically increments the run's summary counters based on `action_type`.

package/templates/self-healing.md

@@ -17,7 +17,7 @@ permissions:
 mcp-servers:
   recapt:
     command: npx
-    args: ["@recapt/mcp"]
+    args: ["@recapt/mcp@latest"]
     env:
       RECAPT_SECRET_KEY: "${{ secrets.RECAPT_SECRET_KEY }}"
     allowed: ["*"]