Fix Sentry

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

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):

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

Run git diff --stat and classify changed files:

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:

   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:

   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

Evaluation Criteria

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)