@recapt/mcp 0.0.18-beta → 0.0.20-beta

package/skills/self-improvement.md

@@ -1,6 +1,6 @@
 # Recapt Self-Improvement Workflow
 
-Use this workflow when asked to "improve the site" or enhance UX based on behavioral data from recapt.
+Use this workflow when asked to "improve the site" or improve UX based on behavioral data from recapt.
 
 ## When to Use
 
@@ -11,11 +11,14 @@ This is a **comprehensive site improvement workflow**. Only use it when the user
 - "Analyze my whole site and improve it"
 - "Do a full UX audit"
 - "Make general improvements across the site"
-  **Do NOT use this workflow for:**
+
+**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.
+
+For specific requests, use the appropriate tools directly — let the conversation guide which tools to call.
 
 ## Run Tracking
 
@@ -25,143 +28,201 @@ At the start of each improvement session, register the run to track progress and
 
 ```
 const response = await start_improvement_run({
-  trigger_type: "manual",  // or "github_actions", "cron", "api"
-  trigger_metadata: { ... },  // optional: branch, actor, etc.
+  trigger_type: "manual",
+  trigger_metadata: { ... },
   phases: [
+    { name: "evaluate", status: "pending" },
     { name: "diagnose", status: "pending" },
-    { name: "investigate", status: "pending" },
-    { name: "fix", status: "pending" },
-    { name: "track", status: "pending" }
+    { name: "triage", status: "pending" },
+    { name: "fix", status: "pending" }
   ]
 })
 
-// IMPORTANT: Extract the run ID from the response
-const run_id = response.id;  // e.g., "682d1a2b3c4d5e6f7a8b9c0d"
+const run_id = response.id;
 ```
 
 This creates a run record visible in the Improvement Runs UI. **You must update the run as you progress through each phase.**
 
-### Phase Progress Updates
+## Workflow
+
+### 0. Check Prs
+
+<!-- @if in-house -->
+<!-- Skip this phase in in-house mode - PR checking is handled by the orchestrator -->
+<!-- @endif -->
 
-Update the run status at each phase transition. Always pass the complete phases array with updated statuses:
+## Check Pending Fixes
 
-**After starting diagnose:**
+Before diagnosing new issues, check fixes in various states.
+
+<!-- @if in-house-fix -->
+
+Use the organization's GitHub token for all git operations.
+
+<!-- @endif -->
+
+### Check PR Status for Waiting Fixes
 
 ```
-update_improvement_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" }
-  ]
-})
+list_remediations_by_status({ statuses: ["waiting"] })
 ```
 
-**After completing diagnose (before investigate):**
+For each waiting fix with a PR number, check PR status:
 
+```bash
+gh pr view <pr_number> --json state,mergedAt,closedAt
 ```
-update_improvement_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 }
-})
+
+Update based on PR state:
+
+- If merged → `update_remediation_status({ status: "deployed", pr_merged_at: <mergedAt> })`
+- If closed (not merged) → `update_remediation_status({ status: "dismissed", pr_closed_at: <closedAt> })`
+- If still open → Leave as "waiting"
+
+### 1. Evaluate
+
+Check if any previously deployed fixes have had enough time to collect data for evaluation.
+
+### Check for Waiting PRs
+
+First, check if any fixes are waiting for PR merge:
+
+```
+list_remediations_by_status({ statuses: ["waiting"] })
 ```
 
-**After completing investigate (before fix):**
+For each waiting fix, ask the user about the PR status:
+
+- If the PR was merged → update to `deployed` with `update_remediation_status`
+- If the PR was closed without merge → update to `dismissed`
+- If still open → leave as `waiting`
+
+### Check for Deployed Fixes
 
 ```
-update_improvement_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" }
-  ]
-})
+list_remediations_by_status({ statuses: ["deployed"] })
 ```
 
-**After completing fix (before track):**
+For each deployed fix where `deployedAt` is more than 24 hours ago:
+
+1. **Fetch current metrics** using `evaluate_fix`:
 
 ```
-update_improvement_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 }
+evaluate_fix({
+  remediation_id: "<remediation_id>",
+  min_hours: 24
 })
 ```
 
-**After completing track (run complete):**
+2. **Analyze the results**:
+   - If `outcome` is `success`: The fix worked! Metrics improved significantly.
+   - If `outcome` is `partial`: Some improvement, but not conclusive.
+   - If `outcome` is `failed`: The fix didn't help. Metrics unchanged or worse.
+   - If `outcome` is `insufficient_data`: Not enough sessions yet. Leave as deployed.
+
+3. **Record lessons learned** if the fix failed:
+   - Use `add_site_knowledge` to document what didn't work
+   - Include the hypothesis, what was tried, and why it may have failed
+   - This helps future fix attempts avoid the same mistakes
+
+4. **Record the evaluation action** to the improvement run:
 
 ```
-update_improvement_run({
+record_improvement_action({
   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
+  remediation_id: "<remediation_id>",
+  action_type: "evaluation",
+  hypothesis: "<original fix hypothesis>",
+  expected_improvement: "<what was expected>",
+  evaluation_result: {
+    outcome: "<success|partial|failed|insufficient_data>",
+    verdict: "<evaluation verdict>",
+    delta: { frustration: <change>, healthScore: <change> }
   }
 })
 ```
 
-## Workflow
-
-### 0. Check Pending Fixes (if returning)
-
-Before diagnosing new issues, check if there are previously tracked fixes awaiting validation:
+5. **Update remediation status** based on the outcome:
 
-- Search: "pending fixes" → `list_pending_fixes`
+```
+update_remediation_status({
+  remediation_id: "<remediation_id>",
+  status: "<succeeded|failed>"  // Only if outcome is success or failed
+})
+```
 
-If pending fixes exist:
+- If `outcome` is `success` → status `succeeded`
+- If `outcome` is `failed` → status `failed`
+- If `outcome` is `partial` or `insufficient_data` → leave as `deployed` (will re-evaluate later)
 
-1. For each fix, call `evaluate_fix` to check validation status
-2. The tool will indicate if sufficient time has passed and enough sessions have interacted with the affected areas
-3. If data is insufficient, inform the user:
+### Output
 
-> "You have X fixes deployed Y hours ago. We need more session data (or more time) before we can validate their impact. Want to proceed with diagnosing new issues, or check back later?"
+Summarize the evaluation results:
 
-If fixes have sufficient data:
+- What fixes were evaluated?
+- What were the baseline vs post-deploy metrics?
+- What is the verdict for each?
+- If any failed, what lessons were learned?
 
-- Present the validation results (improved, no change, or regressed)
-- Discuss next steps for any fixes that didn't improve metrics
-- Then proceed to diagnose new issues
+If no fixes are ready for evaluation, proceed to the next phase.
 
-### 1. Diagnose
+### 2. 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.
 
-After diagnosis completes, **update the phase to "completed"** and set `summary.issuesFound`.
+The diagnostic response includes key metrics you must capture:
+
+- `summary.overall_health_score` — Site health score (0-100)
+- `summary.total_sessions` — Number of sessions analyzed
+- `summary.pages_analyzed` — Number of pages with data
+
+After diagnosis completes:
+
+1. **Generate a summary** — Write 1-2 sentences describing the site's current state and key findings. Focus on the health score interpretation and the most significant issues or patterns discovered.
+2. **Update the run with diagnostic data** — Pass the `diagnostic` object to preserve this information for the UI.
+
+```
+// Extract from run_full_diagnostic response
+const { overall_health_score, total_sessions, pages_analyzed, total_issues } = diagnosticResult.summary;
+
+// Generate a concise summary based on findings
+const diagnosticSummary = generateSummary(diagnosticResult);
+
+update_improvement_run({
+  run_id: "<run_id>",
+  diagnostic: {
+    healthScore: overall_health_score,
+    totalSessions: total_sessions,
+    pagesAnalyzed: pages_analyzed,
+    summary: diagnosticSummary
+  },
+  phases: [
+    { name: "evaluate", status: "completed" },
+    { name: "diagnose", status: "completed", completedAt: new Date().toISOString(), output: { issuesFound: total_issues } },
+    { name: "triage", status: "running", startedAt: new Date().toISOString() },
+    { name: "fix", status: "pending" }
+  ],
+  summary: { issuesFound: total_issues }
+})
+```
+
+**Summary writing guidelines:**
+
+- Start with the health score interpretation (excellent/good/needs work/poor/critical)
+- Mention the most significant finding (top issue category, problem page, or positive observation)
+- Keep it to 1-2 sentences, under 200 characters
+- Examples:
+  - "Your site is healthy at 92/100. Minor friction detected on the pricing page with users hesitating at the plan selector."
+  - "Site health is concerning at 58/100. Critical rage clicks on the checkout button suggest a broken interaction."
+  - "Excellent health score of 95/100. No critical issues found, but the onboarding flow could be streamlined."
 
-### 2. Analyze Flows
+### Analyze Flows
 
 After diagnosing issues, proactively look for flow optimization opportunities — even when nothing is "broken."
 
-#### 2a. Discover Journey Patterns
+#### Discover Journey Patterns
 
 - Search: "journey patterns" → `get_journey_patterns`
 - Look for:
@@ -169,7 +230,7 @@ After diagnosing issues, proactively look for flow optimization opportunities
   - **Dropoff pages** — where sessions end unexpectedly (potential conversion leaks)
   - **Unexpected paths** — users taking roundabout routes to reach goals
 
-#### 2b. Analyze Key Funnels
+#### Analyze Key Funnels
 
 - Search: "analyze funnel" → `analyze_funnel`
 - Analyze critical conversion paths:
@@ -181,7 +242,7 @@ After diagnosing issues, proactively look for flow optimization opportunities
   - Frustration/confusion scores
   - Dwell time anomalies
 
-#### 2c. Analyze Specific Flows
+#### Analyze Specific Flows
 
 - Search: "analyze flow" → `analyze_flow`, `get_flow_friction`
 - For pages with high dropoff or backtracking, analyze the flow in detail:
@@ -189,7 +250,7 @@ After diagnosing issues, proactively look for flow optimization opportunities
   - Where are the bottlenecks?
   - What's the friction score at each step?
 
-#### 2d. Understand User Segments
+#### Understand User Segments
 
 - Search: "personas" → `discover_personas`
 - Identify behavioral personas:
@@ -197,7 +258,7 @@ After diagnosing issues, proactively look for flow optimization opportunities
   - What are their risk factors?
   - What interventions are recommended?
 
-#### 2e. Compare Success vs Failure
+#### Compare Success vs Failure
 
 - Search: "compare cohorts" → `compare_cohorts`
 - For flows with low conversion, compare:
@@ -206,7 +267,49 @@ After diagnosing issues, proactively look for flow optimization opportunities
   - New vs returning users
 - Look for patterns: What do successful users do differently?
 
-#### Presenting Flow Opportunities
+### 3. 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)
+- Some flow patterns may be acceptable (e.g., users comparing options before deciding)
+- Ask the user which issues and opportunities to address before proceeding
+
+<!-- @if in-house-audit -->
+
+### Audit Mode: Surface All Issues
+
+In Audit Mode, save all identified issues to the database for manual review:
+
+1. For each issue found, save it with status `active`
+2. Include behavioral evidence (frustration score, affected sessions, etc.)
+3. Link the issue to this improvement run
+4. **Exit the workflow after saving issues** - do not proceed to the fix phase
+
+The organization will review issues in their dashboard and manually:
+
+- Acknowledge issues they plan to address
+- Mark issues as fixed when resolved
+- Dismiss issues that are not relevant
+
+<!-- @endif -->
+
+### Investigate High-Priority Issues
+
+**Update phase status: mark "diagnose" as completed, "triage" 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
+
+For flow opportunities, also consider:
+
+- Watching session replays of users who dropped off vs completed
+- Checking element friction on high-dropoff pages
+
+### Presenting Findings
 
 Present opportunities alongside issues, clearly labeled:
 
@@ -221,65 +324,162 @@ Present opportunities alongside issues, clearly labeled:
 > 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
+### User Selection
 
-**Update phase status: mark "diagnose" as completed, "investigate" as running.**
+Ask the user which issues to fix. After confirmation, summarize the selected issues:
 
-For each high-priority issue or opportunity, search for investigation tools:
+> **Selected for Fix:**
+>
+> 1. `issue_abc123` - Rage clicks on checkout button (page: /checkout)
+> 2. `issue_def456` - Dead clicks on pricing toggle (page: /pricing)
+>
+> **Dismissed:**
+>
+> - `issue_xyz789` - Marked as intended behavior (copy button)
+>
+> **Deferred:**
+>
+> - `opp_001` - Mobile checkout UX (needs more investigation)
 
-- Search: "investigate issue" → `investigate_issue`, `validate_issue`
-- This provides detailed context: affected sessions, element interactions, timing patterns
+For dismissed issues, call `dismiss_issue` or `mark_intended_behavior` to record the decision.
 
-For flow opportunities, also consider:
+**After triage, update phase status: mark "triage" as completed, "fix" as running.**
 
-- Watching session replays of users who dropped off vs completed
-- Checking element friction on high-dropoff pages
+<!-- @if in-house-audit -->
 
-### 4. Triage
+**In Audit Mode: Exit workflow here. Do not proceed to the fix phase.**
 
-Present findings to the user. Not all detected issues need fixing:
+<!-- @endif -->
 
-- Search: "dismiss issue" → `dismiss_issue`, `mark_intended_behavior`
-- Some behaviors are intentional (e.g., rage clicks on a "copy" button)
-- Some flow patterns may be acceptable (e.g., users comparing options before deciding)
-- Ask the user which issues and opportunities to address before proceeding
+### 4. Fix
+
+<!-- @if in-house-audit -->
+
+**This phase is skipped in Audit Mode.** Issues have been saved to the database for manual review.
+
+<!-- @endif -->
+
+<!-- @if no-git -->
+
+**This phase is skipped when GitHub is not connected.** Issues have been saved to the database for manual tracking.
+
+<!-- @endif -->
+
+You are a UX engineer fixing issues identified by recapt behavioral intelligence.
 
-**After triage, update phase status: mark "investigate" as completed, "fix" as running.**
+<!-- @if in-house-fix -->
 
-### 5. Fix
+### In-House Fix Mode
 
-Implement code changes to address issues and opportunities. After making changes:
+You are running in Fix Mode with GitHub connected. Use the organization's GitHub token for all git operations:
 
-- Search: "propose fix" → `propose_fix`, `get_similar_fixes`, `get_fix_history`
-- Log the remediation so recapt can track its effectiveness
+- Create branches and PRs using the GitHub API
+- Include a link to the recapt dashboard in PR descriptions
+- PRs should be created as drafts for human review
 
-**Note:** `propose_fix` accepts either `issue_id` (for formal issues) or `page_path` + `element_selector` (for element friction fixes without a formal issue).
+<!-- @endif -->
 
-**Record each action in the improvement run.** You MUST call `record_improvement_action` for EVERY issue — whether fixed, deferred, or dismissed. The UI tabs are populated from these action records, not from the summary counters.
+### Workflow
+
+#### 1. Investigate the Issue
+
+Get detailed context about the issue:
+
+```
+investigate_issue({ issue_id: "<issue_id>" })
+```
+
+This provides:
+
+- Affected sessions and their behavioral patterns
+- Element interactions and timing
+- Console errors if any
+- Similar issues on other pages
+
+#### 2. Check Similar Fixes
+
+Before implementing, check if similar issues have been fixed before:
+
+```
+get_similar_fixes({
+  page_path: "<page_path>",
+  category: "<issue_category>"
+})
+```
+
+Learn from past attempts - what worked, what didn't.
+
+#### 3. Validate the Issue
+
+Confirm the issue is still occurring and worth fixing:
+
+```
+validate_issue({ issue_id: "<issue_id>" })
+```
+
+If the issue has resolved itself or has very low occurrence, you may skip fixing it.
+
+#### 4. Propose the Fix
+
+Before implementing, create a remediation record to capture baseline metrics:
+
+```
+propose_fix({
+  issue_id: "<issue_id>",
+  diagnosis: "<your analysis of the root cause>",
+  proposed_fix: "<description of what you plan to change>",
+  affected_files: ["<path/to/file1>", "<path/to/file2>"],
+  confidence: 0.8  // 0-1, how confident you are this will fix the issue
+})
+```
+
+Save the `remediation_id` from the response — you'll need it for tracking.
+
+#### 5. Implement the Fix
+
+Based on your investigation:
+
+1. **Identify the root cause** - What's causing the user friction?
+2. **Design the fix** - What code changes will address it?
+3. **Make the changes** - Edit the relevant files
+
+Common fix patterns by category:
+
+- **rage_clicks**: Add loading states, fix unresponsive buttons, handle errors
+- **dead_clicks**: Make elements interactive or remove click affordances
+- **form_friction**: Improve validation, add inline errors, simplify fields
+- **navigation_confusion**: Improve CTAs, add breadcrumbs, clarify hierarchy
+- **backtracking**: Add missing information to reduce backtracking
+- **abandonment**: Simplify forms to reduce abandonment
+- **multi-step flows**: Add progress indicators
+- **decision points**: Improve CTAs and visual hierarchy, add social proof or trust signals
+
+#### 7. Record the Action
+
+**Record each action in the improvement run.** You MUST call `record_improvement_action` for EVERY issue — whether fixed, deferred, or dismissed.
 
 **For code fixes:**
 
 ```
 record_improvement_action({
   run_id: "<run_id>",
-  issue_id: "<issue_id>",  // optional - omit for element friction fixes
+  issue_id: "<issue_id>",
   action_type: "code_fix",
-  hypothesis: "The checkout button is unresponsive due to a JS error...",
-  expected_improvement: "Fixing the error handler should reduce rage clicks by 50%",
+  hypothesis: "<your diagnosis of the root cause>",
+  expected_improvement: "<what metrics should improve>",
   code_changes: [{
-    file: "src/components/Checkout.tsx",
-    startLine: 45,  // line number where the change starts
-    linesAdded: 5,
-    linesRemoved: 2,
-    diff: "@@ -45,7 +45,10 @@\n-  const handleClick = () => {\n+  const handleClick = async () => {\n+    try {\n       await processPayment();\n+    } catch (err) {\n+      setError(err.message);\n+    }\n   };"
+    file: "<path to file>",
+    startLine: <line number>,
+    linesAdded: <count>,
+    linesRemoved: <count>,
+    diff: "<unified diff format>"
   }],
-  pr_url: "https://github.com/...",
-  pr_number: 123,
-  remediation_id: "<remediation_id>"  // from propose_fix response.id
+  page_path: "<page_path>",
+  remediation_id: "<remediation_id>"  // from propose_fix response
 })
 ```
 
-**CRITICAL: The `diff` field must contain actual unified diff format** (like `git diff` output), NOT a description of what changed. Include the `@@` hunk header, `-` for removed lines, `+` for added lines. The UI renders this as a syntax-highlighted diff viewer.
+**CRITICAL: The `diff` field must contain actual unified diff format** (like `git diff` output), NOT a description of what changed.
 
 **For deferred issues (needs more data):**
 
@@ -288,9 +488,9 @@ record_improvement_action({
   run_id: "<run_id>",
   issue_id: "<issue_id>",
   action_type: "needs_more_data",
-  hypothesis: "Users may be rage-clicking the save button, but only 3 sessions show this pattern.",
-  expected_improvement: "With more data, we can confirm if this is a real issue or noise.",
-  deferral_reason: "Only 3 sessions in the last 7 days. Need at least 10 sessions to validate."
+  hypothesis: "<what you think might be the cause>",
+  expected_improvement: "N/A",
+  deferral_reason: "<why you couldn't fix it>"
 })
 ```
 
@@ -300,42 +500,52 @@ record_improvement_action({
 record_improvement_action({
   run_id: "<run_id>",
   issue_id: "<issue_id>",
-  action_type: "dismissed",  // or "marked_intended"
-  hypothesis: "Rage clicks detected on the copy-to-clipboard button.",
-  expected_improvement: "N/A - this is expected behavior.",
-  dismissal_reason: "Users click multiple times to confirm the copy action. This is intentional UX."
+  action_type: "dismissed",
+  hypothesis: "<what the issue appeared to be>",
+  expected_improvement: "N/A",
+  dismissal_reason: "<why this is intentional or not worth fixing>"
 })
 ```
 
-For flow optimizations, common fixes include:
+#### 8. Update Remediation Status
+
+Mark the remediation as proposed (changes made locally):
 
-- 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
+```
+update_remediation_status({
+  remediation_id: "<remediation_id>",  // from propose_fix response
+  status: "proposed"
+})
+```
 
-### 6. Track
+The user can deploy the changes and then call `confirm_deployment` to start tracking.
 
-**Update phase status: mark "fix" as completed, "track" as running.**
+### Track Deployments
 
 Mark fixes as deployed so recapt can measure impact:
 
 - Search: "deployment" → `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`
 
-**Complete the improvement run when done:**
+### Complete the Improvement Run
+
+Before completing the run, generate a concise title that summarizes what was fixed:
+
+- Be 3-8 words, describing the key fixes made
+- Focus on the most impactful changes
+- Use action verbs (e.g., "Fixed", "Improved", "Resolved")
 
 ```
 update_improvement_run({
   run_id: "<run_id>",
   status: "completed",
+  title: "<GENERATE_TITLE_BASED_ON_FIXES>",
   completed_at: new Date().toISOString(),
   duration_ms: <elapsed_time>,
   phases: [
+    { name: "evaluate", status: "completed", ... },
     { name: "diagnose", status: "completed", ... },
-    { name: "investigate", status: "completed", ... },
-    { name: "fix", status: "completed", ... },
-    { name: "track", status: "completed", completedAt: new Date().toISOString() }
+    { name: "triage", status: "completed", ... },
+    { name: "fix", status: "completed", completedAt: new Date().toISOString() }
   ],
   summary: {
     issuesFound: 5,
@@ -347,7 +557,22 @@ update_improvement_run({
 })
 ```
 
-### 7. Learn
+### Build Site Knowledge
+
+Build site knowledge for future reference:
+
+- Search: "site knowledge" → `get_site_knowledge`, `add_site_knowledge`
+- Document patterns, intended behaviors, and architectural decisions
+
+### Output
+
+Summarize what you did:
+
+- What was the issue?
+- What was the root cause?
+- What fix did you implement?
+
+### 6. Learn
 
 Build site knowledge for future reference:
 
@@ -369,78 +594,19 @@ If the user agrees:
 
 ## Tool Discovery Reference
 
-| Phase         | Search Query        | Tools                                                                                                   |
-| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------- |
-| Run Tracking  | "improvement run"   | `start_improvement_run`, `update_improvement_run`, `record_improvement_action`, `list_improvement_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
-
-Improvement 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_improvement_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_improvement_run` and `record_improvement_action`
-
-### record_improvement_action
-
-```json
-{
-  "id": "682d1a2b3c4d5e6f7a8b9c11",
-  "improvementRunId": "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`.
+| Phase         | Search Query         | Tools                                                                                                   |
+| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
+| Run Tracking  | "improvement run"    | `start_improvement_run`, `update_improvement_run`, `record_improvement_action`, `list_improvement_runs` |
+| Check PRs     | "remediation status" | `list_remediations_by_status`, `update_remediation_status`, `get_remediation_by_pr`                     |
+| 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`                                                              |