sentry-triage

# Sentry Triage ## Overview Automatically triage the highest-impact unresolved Sentry issues using systematic root cause analysis. Filters out user-specific flukes, writes a plan for real bugs, reproduces them with tests, and fixes them. **Core principle:** Find root cause before attempting fixes. Never ship a fix without a failing test first. **Violating the letter of this process is violating the spirit of debugging.** ## Sentry Configuration - Org: `cellm` - Region URL: `https://de.sentry.io` - Project: `client` ## The Process You MUST complete each phase before proceeding to the next. ### Phase 1: Load and Rank Issues 1. **Fetch top unresolved issues sorted by frequency:** ``` mcp__sentry__list_issues( organizationSlug='cellm', regionUrl='https://de.sentry.io', projectSlugOrId='client', query='is:unresolved', sort='freq', limit=5 ) ``` 2. **Present the issues to the user** as a numbered list with: - Issue ID - Title / error message - Event count - User count (if available) - First seen / last seen 3. **Pick the highest-impact issue** (most frequent + most users affected). Present your choice and reasoning. Ask the user to confirm or pick a different one. ### Phase 2: Root Cause Investigation **BEFORE attempting ANY fix:** 1. **Get full issue details:** ``` mcp__sentry__get_sentry_resource( resourceType='issue', organizationSlug='cellm', resourceId='<issue-short-id>' ) ``` 2. **Get recent events for context:** ``` mcp__sentry__list_issue_events( issueId='<issue-short-id>', organizationSlug='cellm', regionUrl='https://de.sentry.io', limit=5 ) ``` 3. **Optionally run Seer analysis** if the stack trace alone is not enough to understand root cause: ``` mcp__sentry__analyze_issue_with_seer( organizationSlug='cellm', regionUrl='https://de.sentry.io', issueId='<issue-short-id>' ) ``` 4. **Read the error messages and stack traces carefully.** Don't skip past them. 5. **Trace backward through the call chain** to find the original trigger. Don't stop at where the error appears - trace up until you find the source. Read the actual source files in the codebase at each level of the stack. 6. **Check recent changes** that could have caused the issue (git log, git diff). ### Phase 3: Classify the Issue After investigation, classify the issue into one of two categories: #### Category A: User-Specific / Environmental Issues caused by the user's specific environment that we cannot and should not fix in code. Examples: - File or folder permission errors on the user's machine - Incorrect provider API URLs configured by the user - Missing API keys or expired tokens - Antivirus or firewall blocking requests - Corrupted local Excel installation - Network-specific issues (corporate proxy, VPN) - OS-specific quirks unique to one machine **If Category A:** STOP. Present your findings to the user: ``` I believe this issue is user-specific and should be marked as resolved without a code change. **Issue:** <title> **Evidence:** <what you found in the events/stack trace> **Why it's environmental:** <specific reasoning - e.g., "All 3 events come from the same user, the error is a file permission denied on a path specific to their machine"> **Impact of fixing in code:** This would affect all users unnecessarily. Should I mark this as resolved in Sentry? ``` Wait for the user to confirm before marking as resolved. #### Category B: Real Bug The issue is caused by a defect in our code that affects or could affect any user. **If Category B:** Proceed to Phase 4. ### Phase 4: Hypothesis 1. **State your hypothesis clearly:** - "I think X is the root cause because Y" - Be specific, not vague - Reference exact file paths and line numbers 2. **Identify what evidence would confirm or reject the hypothesis:** - What behavior would a test need to demonstrate? - What input triggers the bug? - What is the expected vs actual output? 3. **Present hypothesis to the user** for validation before proceeding. ### Phase 5: Write a Plan **REQUIRED SUB-SKILL:** Invoke `superpowers:writing-plans` to create a plan. The plan should cover: 1. **Write a failing test** that reproduces the bug based on the hypothesis - Prefer a **unit test** if the bug can be isolated to a single component - If the bug requires Excel interaction, write an **integration test** - If neither is possible, STOP and ask the user what to do 2. **Run the test** to confirm it fails (RED) 3. **Write the minimal fix** that makes the test pass 4. **Run the test** to confirm it passes (GREEN) 5. **Run the full test suite** to confirm no regressions The plan validates the hypothesis: if the test fails as predicted, the hypothesis is confirmed. If the test passes unexpectedly, the hypothesis is rejected - return to Phase 4 with new information. ### Phase 6: Execute the Plan **REQUIRED SUB-SKILL:** Invoke `superpowers:executing-plans` to execute the plan task by task. ### Phase 7: Wrap Up After the fix is verified: 1. **Present a suggested commit message** to the user (do NOT commit yourself) 2. **Ask the user** if the Sentry issue should be marked as resolved ## Red Flags - STOP and Return to Phase 2 If you catch yourself: - Proposing a fix without reading the stack trace - Fixing where the error appears instead of where it originates - Skipping the hypothesis step - Writing a fix without a failing test - "It's probably X, let me just fix that" - Changing code that affects all users for a user-specific issue **ALL of these mean: STOP. Return to Phase 2.** ## Test Guidelines When writing tests for Sentry issues: - **Unit tests:** Use real `ConfigureServices` DI setup, only mock Excel-dependent services - **Missing API keys:** Tests must fail loudly with `Assert.Fail`, never skip silently - **Run only relevant tests:** API calls cost money, only run tests for the provider being worked on - **Always run `dotnet format`** before suggesting a commit ## Quick Reference | Phase | Key Activity | Gate | |-------|-------------|------| | **1. Load Issues** | Fetch top 5, pick highest impact | User confirms issue choice | | **2. Investigate** | Stack traces, events, source code | Understand WHAT and WHY | | **3. Classify** | Environmental vs real bug | User confirms classification | | **4. Hypothesis** | State root cause theory | User validates hypothesis | | **5. Plan** | Use writing-plans skill | Plan reviewed | | **6. Execute** | Use executing-plans skill | Tests pass, no regressions | | **7. Wrap Up** | Suggest commit, resolve issue | User commits |