# Sentry Triage

> Use when triaging production bugs from Sentry, debugging unresolved issues, or when asked to check Sentry for errors

- Skill: `getcellm/sentry-triage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add getcellm/sentry-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/getcellm/sentry-triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: getcellm (https://skillmd.com/u/getcellm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/getcellm/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 |