fix-sentry

# Fix Sentry Skill

Automated workflow: Sentry issues → analyze → fix → GitHub Issue → PR.

**Announce at start:** "I'm using fix-sentry skill to find and fix high-frequency Sentry issues."

## Operating Modes

### Batch Mode (default)

Invocation: `/fix-sentry` or `/fix-sentry threshold=50`

- Uses the specified threshold (default 100) to fetch issues
- Runs full Phase 1 → Phase 2 → Phase 3
- Fixes all qualifying issues

### Daemon Mode

Invocation: `/fix-sentry limit=1` (from daemon script)

- Phase 1 uses **adaptive threshold descent**: starts at 100, lowers progressively until a fixable issue is found
- Fixes only 1 issue (controlled by `limit` parameter), then exits
- If no fixable issue exists at any threshold → outputs `[NO_FIXABLE_ISSUES]` and exits

## Prerequisites

- **Sentry MCP** must be configured (global or project scope) with `mcp__sentry__*` tools available
- **gh CLI** must be authenticated
- Working directory must be clean (`git status` shows no uncommitted changes)

## Workflow

### Phase 1: Collect & Filter Issues

#### Step 1.1: Verify Environment

```bash
git status --porcelain   # must be clean
git branch --show-current
```

If working directory is dirty, **STOP** and ask user to commit or stash first.

#### Step 1.1b: Load Skip List (Daemon Mode Only)

In daemon mode (`limit > 0`), load the skip list to avoid re-analyzing issues that were already
triaged in previous sessions. The skip list is stored at:

```
~/.wayland-fix-sentry/skip-list.json
```

Format:

```json
{
  "ELECTRON-6X": { "reason": "already_fixed", "expires": "2026-03-28T03:00:00Z", "summary": "PR #1758 merged" },
  "ELECTRON-A7": { "reason": "system_level", "expires": "2026-04-03T03:00:00Z", "summary": "EPIPE in net.Socket" }
}
```

**On load:**

1. Read the file (if it doesn't exist, start with an empty skip list)
2. Remove all entries where `expires` < current time (expired entries get re-analyzed)
3. Keep the remaining entries as the active skip list

**During Phase 1.2 (Fetch Issues):**

When iterating through fetched issues, if an issue's short ID (e.g., `ELECTRON-6X`) is in the
active skip list, **skip it immediately** without calling `get_issue_details` or doing any analysis.
Log the skip: `Skipping ELECTRON-6X (cached: already_fixed - PR #1758 merged)`

**In batch mode (`limit=0`):** skip list is ignored - always analyze everything fresh.

#### Step 1.2: Fetch Unresolved Issues

**Always include `is:unresolved`** to exclude issues already marked as resolved in Sentry.

##### Batch mode (no `limit` parameter or `limit=0`)

Use the specified `threshold` parameter (default 100) directly:

```
mcp__sentry__list_issues(
  projectSlugOrId="<project>",
  query="times_seen:><threshold> is:unresolved",
  sort="freq",
  limit=25
)
```

##### Daemon mode (`limit > 0`): Adaptive Threshold Descent

When `limit` is set, use **adaptive threshold descent** to find fixable issues. Start high and
lower progressively - this ensures the most impactful issues are fixed first.

**Threshold sequence:** 100 → 80 → 60 → 40 → 20 → 10

For each threshold in the sequence:

1. Fetch issues: `mcp__sentry__list_issues(query="times_seen:><threshold> is:unresolved", sort="freq", limit=25)`
2. Run Steps 1.3–1.6 (filter, deduplicate, triage)
3. If any "Needs fix" issues are found → proceed to Phase 2 with the top `limit` issues
4. If all issues are skipped (already fixed, system-level, unfixable) → log and try the next lower threshold

If **all thresholds are exhausted** with no fixable issues, enter **Deep Analysis Mode** (Step 1.2b).

##### Step 1.2b: Deep Analysis Mode - Issues Without Stack Traces

When no fixable issues remain at any standard threshold, search for issues that lack stack traces
but may still be fixable through code analysis:

```
mcp__sentry__list_issues(
  projectSlugOrId="<project>",
  query="!has:stacktrace is:unresolved",
  sort="freq",
  limit=10
)
```

For these issues, apply **Step C (Defensive fix)** logic from Step 1.6:

- Extract distinctive patterns from the error message (file names, paths, keywords)
- Search the codebase for matching code paths
- If a matching code path is found → classify as "Defensive fix" and proceed to Phase 2

If deep analysis also yields no fixable issues, output the following **exact text** and exit:

```
[NO_FIXABLE_ISSUES] All thresholds exhausted, no actionable issues found.
```

**This marker is machine-readable** - the daemon script uses it to determine backoff timing.

#### Step 1.3: Evidence-Based Filtering

Determine whether each issue has already been addressed. **Only skip issues with concrete evidence
of a fix** - version distribution alone is NOT sufficient to conclude an issue is fixed (the latest
release may simply have fewer users).

1. **Get the latest release version:**

   ```bash
   gh release list --repo <org>/<repo> --limit 3
   ```

2. **Search for existing fixes (concrete evidence required):**

   ```bash
   gh release view <latest-tag> --repo <org>/<repo>
   git log --oneline --since="<release-date>" --grep="<keyword-from-error>"
   ```

3. **Cross-reference with Sentry issue metadata:**
   - If the issue has a GitHub annotation linking to a **merged** PR, skip it
   - If the issue status is `resolved` with `inRelease`, skip it
   - If release notes explicitly mention a fix for this error, skip it

4. **Check for existing OPEN PRs:**

   ```bash
   gh pr list --repo <org>/<repo> --state open --search "<error-keyword>" --json number,title,state
   ```

   - If an OPEN PR already addresses this issue, do NOT create a duplicate
   - Classify as **"fix pending merge"** - the issue is still occurring because the fix hasn't been deployed yet
   - If the OPEN PR has quality issues (e.g., missing tests), note it for improvement

**Important: version distribution is supplementary info, NOT a skip criterion.**
"Only seen on v1.8.30, not on v1.8.31" does NOT mean the issue is fixed - the latest version
may have too few users to trigger the error. Includ