---
name: fix-sentry
description: "Scan all unresolved Sentry errors, group by root cause, fix in batch with TDD, and resolve in Sentry after deploy. Use when the user says 'fix sentry errors', 'scan sentry', 'resolve sentry issues', 'fix all errors', 'sentry cleanup', or wants to proactively fix production errors from Sentry monitoring."
---

# Fix Sentry Errors

Proactively scan Sentry for all unresolved errors, group them by root cause, create a unified fix plan, implement with TDD, review, deploy, and resolve the issues in Sentry.

## Prerequisites

**Read `CONFIG.md` at the start of every run.** This file contains project-specific Sentry settings (org slug, project slug, region URL, deploy provider). If `CONFIG.md` doesn't exist, warn the user and point them to `CONFIG.template.md`.

## When to Use

- User wants to proactively fix production errors from Sentry
- User says "fix sentry errors", "scan sentry", "sentry cleanup"
- Periodic maintenance to clear unresolved Sentry issues

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `branch` | `ask` | Branch strategy: `ask` (prompt user), `worktree` (isolated worktree), `main` (commit directly to main) |

## Pipeline Overview

```
Phase 1: Fetch all unresolved errors from Sentry
Phase 2: Triage & group by root cause → ⛔ USER GATE
Phase 3: Diagnose each group (parallel agents) → ⛔ USER GATE
Phase 4: Create unified fix plan (writing-plans)
Phase 5: Implement with TDD (executing-plans)
Phase 6: Review (layered dispatch)
Phase 6.1: Compatibility check (parallel agents)
Phase 6.2: Simplify (/simplify)
Phase 7: Commit & push
Phase 8: Deploy monitor (Vercel MCP polling)
Phase 9: Resolve in Sentry (with verification gate)
Phase 10: Summary
```

---

### Phase 1: Fetch All Unresolved Errors

**Goal:** Retrieve all unresolved Sentry issues for the project.

Read Sentry config from `CONFIG.md`:
- `sentry.org` — org slug
- `sentry.project` — project slug
- `sentry.region_url` — region URL (e.g., `https://us.sentry.io`)

1. **Search for unresolved issues** using Sentry MCP:
   ```
   mcp__claude_ai_Sentry__search_issues
   - org: {sentry.org from CONFIG.md}
   - project: {sentry.project from CONFIG.md}
   - query: "is:unresolved"
   - sort: "events" (most events first)
   ```

2. **Cap at 25 issues.** If more than 25 unresolved issues exist, fetch only the top 25 by event count and warn:
   ```
   ⚠️ Found {N} unresolved issues — fetching top 25 by event count.
   Consider running fix-sentry again for the remainder.
   ```

3. **For each issue (up to 25)**, fetch details using `mcp__claude_ai_Sentry__get_sentry_resource`:
   - Exception type + message
   - Stack trace (top 5 frames)
   - Event count + user count
   - First seen / last seen
   - Tags: browser, environment, URL, release

4. **Compile structured error list** — one entry per issue with all fields above.

**Error handling:**
- If Sentry MCP auth fails: prompt user to authenticate, retry once, abort if still fails
- If no unresolved issues found: report "No unresolved Sentry errors — nothing to fix" and exit

---

### Phase 2: Triage & Group ⛔ USER GATE

**Goal:** Cluster errors by root cause, rank by impact, and get user's scope decision.

1. **Cluster errors by root cause** using these rules:
   - Same file + same function → same group
   - Related stack traces (shared caller chain) → same group
   - Same error message with different URLs → same group

2. **Rank groups by impact:** `event_count × user_count` (highest first)

3. **Present to user:**
   ```
   Found {N} unresolved errors in {M} groups:

   | # | Group | Errors | Events | Users | Root File |
   |---|-------|--------|--------|-------|-----------|
   | 1 | {description} | 5 | 120 | 45 | lib/services/foo.ts |
   | 2 | {description} | 3 | 80 | 20 | app/api/bar/route.ts |
   ...

   Fix all / Pick specific groups / Cap at top N?
   ```

4. **If >10 groups:** suggest splitting across sessions:
   ```
   That's a lot of groups. Recommend picking top 5 for this session
   and running fix-sentry again for the rest.
   ```

**⛔ STOP — wait for user's scope decision before proceeding.**

Store: `selected_groups` for downstream phases.

---

### Phase 3: Diagnose ⛔ USER GATE

**Goal:** Determine root cause for each selected error group using parallel research agents.

For each selected error group, dispatch parallel research agents using `dispatching-parallel-agents`:

**Per group (2 agents in parallel):**

**Agent A — Superpowers Systematic Debugging:**

Spawn a sub-agent with this prompt:
```
Investigate this Sentry error group using the systematic-debugging methodology.

ERROR GROUP: {group_description}
ERRORS IN GROUP: {list of error titles and Sentry IDs}
STACK TRACES: {top 5 frames from each error}
AFFECTED FILES: {files appearing in stack traces}
EVENT COUNT: {total events across group}
USER COUNT: {total affected users}

Follow the 4-phase process:
1. Reproduce: confirm the bug exists in code (read affected files)
2. Find working examples: find similar code that DOES work correctly
3. Compare differences: what's different between working and broken?
4. Form hypothesis: single root cause with evidence

Do NOT fix anything. Do NOT edit any files.

Return a structured summary:
- ROOT_CAUSE: 1-2 sentences
- EVIDENCE: specific code references (file:line)
- AFFECTED_FILES: list with roles
- HYPOTHESIS: what the fix should be
```

**Agent B — gstack /investigate:**

Spawn a sub-agent with this prompt:
```
Debug this Sentry error group using the /investigate methodology (4-phase iron law).

ERROR GROUP: {group_description}
ERRORS IN GROUP: {list of error titles and Sentry IDs}
STACK TRACES: {top 5 frames from each error}
AFFECTED FILES: {files appearing in stack traces}
EVENT COUNT: {total events across group}
USER COUNT: {total affected users}

Follow the iron law: no fixes without root cause.
Phase 1: Investigate — read errors, check recent changes, gather evidence
Phase 2: Analyze — find patterns, compare against references
Phase 3: Hypothesize — form single hypothesis with evidence

Do NOT implement fixes. Do NOT edit any files.

Return a structured summary:
- ROOT_CAUSE: 1-2 sentences
- EVIDENCE: specific code references (file:line)
- AFFECTED_FILES: list with roles
- HYPOTHESIS: what the fix should be
```

**Both agents run in parallel** (`run_in_background: true`). Wait for both to complete.

#### Aggregation (main orchestrator)

After both agents return for each group:

1. **Compare root causes**: Do both agents agree?
2. **If they agree** (high confidence): Merge into a unified finding
3. **If they disagree**: Present both with evidence to the user:
   ```
   Two research agents investigated Group {N} and reached different conclusions:

   **Agent A (systematic-debugging):**
   Root cause: {A's root cause}
   Evidence: {A's evidence}

   **Agent B (/investigate):**
   Root cause: {B's root cause}
   Evidence: {B's evidence}

   Which analysis looks more accurate? (A / B / neither — let me dig deeper)
   ```
   The user's choice becomes the root cause for that group.
4. **Merge affected file lists** (union from both agents)

After all groups diagnosed, present unified diagnosis:
- Per-group root cause + evidence
- Cross-group patterns (shared root causes across groups)
- Total affected files (deduplicated)

**⛔ STOP: "Does this diagnosis look right?"**

Wait for user confirmation before proceeding.

---

### Phase 4: Plan

**Goal:** Create a unified implementation plan for all selected error groups.

Delegate planning to `superpowers writing-plans`:

Spawn a sub-agent with this prompt:
```
Create a unified implementation plan for these Sentry error fixes using the writing-plans methodology.

ERROR GROUPS:
{for each group: group_description, root_cause, affected_files, hypothesis}

CROSS-GROUP PATTERNS:
{shared root causes if any, shared affected files}

PROJECT: Read CLAUDE.md for conventions, patterns, and project structure.

Requirements:
- TDD: every task starts with a failing test
- Group related fixes into the same task when they share files
- Exact file paths, complete code in every step
- Bite-sized tasks (2-5 minutes each)
- Save plan to: docs/superpowers/plans/fix-sentry-{YYYY-MM-DD}.md

Do NOT implement — only plan.
```

Store the returned `plan_file_path` for Phase 5.

---

### Phase 5: Implement

**Goal:** Implement all fixes using TDD methodology.

**MANDATORY: Write a failing test BEFORE implementing each fix.** This proves the error exists and prevents false-positive "fix verified" claims.

Spawn a sub-agent for the implementation:

```
Implement the Sentry error fixes using TDD.

PLAN: {plan_file_path from Phase 4}
ERROR GROUPS: {group summaries with root causes}
PROJECT: Read CLAUDE.md for conventions, patterns, and project structure.

For each task in the plan, follow this sequence strictly:

STEP 1 — RED (prove the error):
Use the test-driven-development methodology.
Write a minimal failing test that demonstrates the error.
The test should assert the CORRECT behavior — it will fail because the bug exists.
Run the test and confirm it FAILS.
If it passes, your test doesn't capture the bug — rewrite it.

STEP 2 — GREEN (fix the error):
Follow the plan from {plan_file_path} using executing-plans.
Make the minimal code change to make the test pass.
Run the test and confirm it PASSES.

STEP 3 — VERIFY:
npm run build 2>&1 | tail -5
npm run lint 2>&1 | tail -5
npm test -- --testPathPattern="{test_file}" 2>&1

Return:
- FILES_CHANGED: list of modified files
- TEST_FILES: paths to new/modified tests
- TEST_RESULT: PASS/FAIL with output
- BUILD_STATUS: PASS/FAIL
- LINT_STATUS: PASS/FAIL
```

**If BUILD or LINT fails:** review the error, fix, re-verify. Max 2 attempts before escalating to user.

**If TEST still FAILS after fix:** the fix is wrong — loop back. Re-analyze using test failure output as new evidence. Max 2 implementation attempts before escalating to user.

---

### Phase 6: Review

**Goal:** Multi-agent code review of all changes.

**MANDATORY. Skip only if Phase 5 used executing-plans with a plan that included its own review cycle.**

#### Layered Review Architecture

Review uses `dispatching-parallel-agents` with two layers:

**Layer 1 — Always run (2 agents):**

| Agent | Skill | Focus |
|-------|-------|-------|
| Plan Compliance Reviewer | `superpowers requesting-code-review` | Do the fixes match the root causes and plan? |
| Structural Reviewer | `gstack /review` | SQL safety, LLM trust boundaries, conditional side effects |

**Layer 2 — Based on diff analysis (1-3 agents):**

Run `git diff --stat` and classify changed files:

| If diff touches... | Add agent |
|-------------------|-----------|
| `catch`, `error`, `throw`, `.catch(` | `pr-review-toolkit:silent-failure-hunter` |
| `type `, `interface `, `z.object`, `z.string` | `pr-review-toolkit:type-design-analyzer` |
| Lines are verbose or deeply nested | `pr-review-toolkit:code-simplifier` |

**Minimum total: 3 agents. Maximum: 5 agents.**

#### Steps

1. Run `git diff --stat` to see the scope of changes
2. Capture BASE_SHA (`git rev-parse HEAD~1`) and HEAD_SHA (`git rev-parse HEAD`) — if no commit yet, use unstaged diff
3. **Select Layer 2 agents** based on the diff classification above
4. **Announce the team**:
   ```
   Spawning {N} review agents: {Agent1} (Layer 1), {Agent2} (Layer 1), {Agent3} (Layer 2), ... — reviewing {N} files, {M} lines changed
   ```
5. **Dispatch all agents in parallel** (`run_in_background: true`):

   **Layer 1 — Plan Compliance** (superpowers requesting-code-review):
   ```
   Review these Sentry error fixes against the requirements.
   WHAT_WAS_IMPLEMENTED: Fixes for {N} Sentry error groups
   PLAN_OR_REQUIREMENTS: {plan_file_path}
   BASE_SHA: {base_sha}
   HEAD_SHA: {head_sha}
   DESCRIPTION: Batch fix for {N} Sentry error groups. Root causes: {summary}.
   ```

   **Layer 1 — Structural** (gstack /review):
   ```
   Pre-landing review of the diff on this branch.
   Run git diff against the base branch.
   Focus on: SQL safety, LLM trust boundaries, conditional side effects, structural issues.
   ```

   **Layer 2 agents** (PR Review Toolkit):
   Each agent receives: `Run git diff to see the changes. This is a read-only review — no edits. Return findings with severity (critical/high/medium/low), file:line, and specific fix suggestion. Max 10 findings.`

6. **Report completion** as each agent finishes:
   ```
   Agent 1 (Plan Compliance): Done — 2 findings (0 critical, 1 high, 1 medium)
   Agent 2 (Structural): Done — 0 findings
   Agent 3 (Silent Failure Hunter): Done — 1 finding (0 critical, 0 high, 1 medium)
   ```

7. **Merge and deduplicate findings**:
   - Group by file:line
   - Keep highest severity when duplicated across agents
   - Cap at 15 findings total
   - Sort by severity (critical → high → medium → low)

**After review completes:**
- **Critical or high issues**: Fix them, re-run build/lint, create a new commit
- **Medium/low issues**: Note them, fix if quick
- **No issues**: Note "No issues found" in summary

**Iteration limit**: Max 2 fix-then-re-review cycles.

---

### Phase 6.1: Compatibility Check

**Goal:** Verify backward compatibility and pattern consistency.

Dispatch 3 parallel sub-agents using `dispatching-parallel-agents`:

**Agent 1 — Backward Compatibility Checker:**
```
Check backward compatibility of the changes on this branch.

Review all modified files. For each, check:
- Exported function signatures: any parameter changes?
- Exported types/interfaces: any removed or renamed fields?
- Server actions: any changed return types?
- API routes: any changed response shapes?

Return findings as:
- SEVERITY: critical/important/minor
- FILE: path
- ISSUE: what broke
- FIX: how to restore compatibility
```

**Agent 2 — Reusability Auditor:**
```
Audit the changes for code reuse opportunities.

Check:
- Any logic in components that should be in lib/?
- Any duplicated code across the changed files?
- Any utility functions that already exist in lib/ being reimplemented?

Return findings as:
- SEVERITY: important/minor
- FILE: path
- ISSUE: what's duplicated or misplaced
- FIX: where to move it
```

**Agent 3 — Pattern Consistency Checker:**
```
Check the changes follow existing project patterns.

Read CLAUDE.md for project conventions. Then review:
- Do new functions follow naming conventions of sibling files?
- Do error handlers follow the catch block rules?
- Do API calls use apiClient?
- Do date operations use parseISO/format?

Return findings as:
- SEVERITY: important/minor
- FILE: path
- ISSUE: what's inconsistent
- FIX: the correct pattern
```

**Fix critical/important findings.** Minor findings: note for future.

---

### Phase 6.2: Simplify

**Goal:** Remove verbosity and ensure DRY compliance.

Invoke `/simplify scope=session`:
- Auto-fix DRY violations
- Remove dead code introduced by the fixes
- Consolidate duplicated logic into lib/ utilities
- Re-run `npm run build` and `npm run lint` if changes are made

---

### Phase 7: Commit & Push

**Goal:** Create a clean commit with all Sentry issue references and push.

1. **Stage all changes:**
   ```bash
   git add -A
   ```

2. **Create commit** with this message format:
   ```
   NO-TICKET: fix: resolve {N} Sentry errors

   Fixes:
   - {SENTRY-ID-1}: {title}
   - {SENTRY-ID-2}: {title}
   - {SENTRY-ID-3}: {title}
   ...

   Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
   ```

3. **Push to remote:**
   ```bash
   git push
   ```

Store: `commit_hash`, `push_status` for Phase 10.

---

### Phase 8: Deploy Monitor

**Goal:** Wait for deployment to complete.

Read deploy provider from `CONFIG.md` (`deploy.provider`). Default: Vercel.

**For Vercel:**
1. Use `mcp__claude_ai_Vercel__list_deployments` to find the latest deployment
2. Poll on this schedule: 45s, 45s, 60s, 60s, 60s, 60s (max 6 polls)
3. Check deployment state each poll:
   - **READY**: deployment succeeded — proceed to Phase 9
   - **ERROR**: read build logs via `mcp__claude_ai_Vercel__get_deployment_build_logs`, diagnose, fix, re-commit, re-push (max 2 retries)
   - **BUILDING/QUEUED**: continue polling

Store: `deploy_status`, `deploy_url` for Phase 10.

**If deploy fails after 2 retries:** report failure and skip Phase 9 (cannot resolve Sentry issues without successful deploy).

---

### Phase 9: Resolve in Sentry ⛔ VERIFICATION GATE

**Goal:** Mark fixed issues as resolved in Sentry, but only after verifying they stopped receiving events.

**Apply `verification-before-completion` discipline:**

1. **Wait 2 minutes** after deploy is READY (allow time for new errors to surface)

2. **For each fixed Sentry issue:**
   a. Check: has the issue received new events since the deploy?
      - Use `mcp__claude_ai_Sentry__search_events` to look for events after the deploy timestamp
   b. **If no new events since deploy:**
      - Mark as resolved via `mcp__claude_ai_Sentry__update_issue` with `status: "resolved"`
   c. **If still receiving events:**
      - Skip resolution
      - Report as "fix may be incomplete — still receiving events"

3. **Report resolution status per issue:**
   ```
   | Issue | Status |
   |-------|--------|
   | {ID-1} | ✅ Resolved |
   | {ID-2} | ✅ Resolved |
   | {ID-3} | ⚠️ Skipped — still receiving events |
   ```

Store: `resolved_count`, `skipped_count`, `skipped_issues` for Phase 10.

---

### Phase 10: Summary

**Goal:** Present a comprehensive summary of all work done.

```
## fix-sentry Complete

**Errors found**: {N} in {M} groups
**Scope**: {all / user-selected groups}
**Commit**: `{hash}` — {subject}
**Deployment**: {Ready at URL / Failed}

### Fixes Applied
| Group | Errors Fixed | Root Cause | Files Changed |
|-------|-------------|------------|---------------|
| 1 | 5 | {cause} | {files} |
| 2 | 3 | {cause} | {files} |

### Sentry Resolution
| Issue | Status |
|-------|--------|
| {ID-1} | ✅ Resolved |
| {ID-2} | ✅ Resolved |
| {ID-3} | ⚠️ Skipped — still receiving events |

### Review Findings
{summary of review findings — issues found and fixed, suggestions deferred}

### Test Coverage
{list of new test files and what they verify}
```

---

## Error Handling

| Scenario | Action |
|----------|--------|
| Sentry MCP auth fails | Prompt user to authenticate, retry once, abort if still fails |
| No unresolved issues found | Report "No unresolved Sentry errors — nothing to fix" and exit |
| Research agents disagree on root cause | Present both to user, user picks |
| Build fails after fix | Diagnose, fix, retry (max 2 attempts), escalate to user |
| Deploy fails | Read logs, fix, re-commit, re-push (max 2 retries) |
| Sentry issue still receiving events after deploy | Skip resolution, report as "fix may be incomplete" |
| >25 unresolved issues | Cap fetch at 25, warn user, suggest multiple sessions |
| >10 error groups | Suggest user picks top N groups for this session |

## Evaluation Criteria

| # | Criterion | Pass | Fail |
|---|-----------|------|------|
| 1 | **Sentry fetch** | Phase 1 fetches all unresolved issues with details (stack trace, event count, user count) | Issues fetched without details, or cap not applied |
| 2 | **Grouping quality** | Phase 2 clusters errors by shared file/function/caller chain, not just error message | Each error treated as separate group, or unrelated errors merged |
| 3 | **User gate (scope)** | Phase 2 stops and waits for user to choose scope before proceeding | Proceeds to Phase 3 without user confirmation |
| 4 | **Parallel diagnosis** | Phase 3 dispatches two agents per group (systematic-debugging + /investigate) | Only one research methodology used |
| 5 | **Disagreement handling** | When agents disagree, both findings presented to user for decision | Disagreement silently resolved or ignored |
| 6 | **User gate (diagnosis)** | Phase 3 stops and waits for user to confirm diagnosis | Proceeds to Phase 4 without user confirmation |
| 7 | **Plan delegation** | Phase 4 delegates to writing-plans with TDD requirement | Plan created inline without TDD structure |
| 8 | **TDD gate** | Phase 5 writes failing test before each fix (RED), then fix (GREEN) | Code changed without test, or test passes before fix |
| 9 | **Review enforcement** | Phase 6 dispatches Layer 1 (code-reviewer + /review) plus 1-3 Layer 2 agents | Review skipped or only 1 agent used |
| 10 | **Compat check** | Phase 6.1 checks backward compatibility, reusability, and pattern consistency | Compat check skipped |
| 11 | **Commit format** | Phase 7 commit lists all Sentry IDs in the message body | Generic commit message without Sentry references |
| 12 | **Deploy monitoring** | Phase 8 polls deployment and handles failures | Deploy status not checked |
| 13 | **Verification gate** | Phase 9 checks for new events before resolving each issue | Issues resolved without event check |
| 14 | **Incomplete fix handling** | Issues still receiving events are skipped, not force-resolved | All issues marked resolved regardless of event status |
| 15 | **Summary completeness** | Phase 10 includes fixes, resolution status, review findings, and test coverage | Summary missing sections or only partial |
| 16 | **Context preservation** | Heavy phases (1, 3, 4, 5, 6, 6.1) run as sub-agents. Main orchestrator stays under 40k tokens. | All phases run inline, burning context |

### Mandatory Checklist (before reporting summary)

- [ ] **Sentry issues fetched**: All unresolved issues retrieved with full details
- [ ] **User approved scope**: User explicitly chose which groups to fix
- [ ] **User approved diagnosis**: User confirmed root causes before planning
- [ ] **TDD tests written**: Failing tests written before fixes for each group
- [ ] **All tests pass**: `npm test` passes after all fixes
- [ ] **Build passes**: `npm run build` succeeds
- [ ] **Lint passes**: `npm run lint` has no errors
- [ ] **Review complete**: At least 3 review agents ran and findings addressed
- [ ] **Deployed**: Deployment succeeded (or failure reported)
- [ ] **Sentry resolved**: Fixed issues marked resolved (or skipped with reason)