Sentry Fix — Auto-Fix Issue with Test

Fix a specific Sentry issue: gather context, confirm with user, implement fix, write regression test, verify, commit.

Arguments

• <ISSUE-ID> (required): Sentry issue short ID, e.g. TEAMCLU-REACT-7Q

The issue ID is passed as the skill argument: /sentry-fix TEAMCLU-REACT-7Q

Projects

Route on the issue ID prefix. Every project's short ID carries its own segment, so the prefix alone identifies the codebase:

ucar-inc/teamclu (a bare TEAMCLU- prefix with no platform segment) is the old, deleted project. An issue ID in that shape is from before 2026-09-04 and cannot be fetched; ask the user for a current one.

teamclu-react covers both the web app and the desktop webview — the desktop Rust process reports separately under teamclu-rust.

Rust tests

Do not run bare cargo test. It exits 101 on teamclu-introspect sidecar binary not found: check/clippy are analysis paths, but test is a real build and runs apps/desktop/build.rs, which panics when binaries/ (entirely gitignored) has no sidecar and CI is unset.

Main checkout — the wrapper builds the sidecar first:

node scripts/rust-cli.js test --manifest-path apps/desktop/Cargo.toml --lib <filter>

Fresh worktree — CI=1 alone is not enough, because tauri-build still globs bundle.resources paths that do not exist there:

CI=1 TAURI_CONFIG='{"bundle":{"externalBin":[],"resources":[]}}' \
  node scripts/rust-cli.js test --manifest-path apps/desktop/Cargo.toml --lib <filter>

Always go through pnpm rust:* / scripts/rust-cli.js rather than bare cargo — bare cargo clippy fails on a fresh checkout for the same reason.

Execution Steps

Phase 1: Gather Context

1. Fetch issue details with stack trace. issue view resolves a short ID across projects, so no slug is needed:

sentry issue view <ISSUE-ID> --json

This is also the only place volume numbers come from — count, userCount, firstSeen and lastSeen are silently dropped from issue list --fields on CLI 0.26.1.

2. From the stack trace and error message, identify the relevant source files and functions in the codebase.

3. Read those source files to understand the code context around the error site.

4. Perform local root cause analysis. Produce a clear root cause summary.

Two checks worth making before writing it up:

• Is this one of several groups for the same defect? A sourcemapped build and a minified one group separately. Search sibling issues for the same metadata.value; if they match, one fix closes all of them, and the plan should say so.
• Is there a group with a sourcemapped frame? Prefer analyzing the one whose culprit is a repo path (/src/...) over a bundle (assets/index-*.js) — it names the file directly instead of needing to be reverse-engineered.

If the stack trace is insufficient to identify the root cause: Stop and ask the user for additional context. Do NOT guess.

Phase 2: Confirm with User

Present a fix plan in the terminal. It MUST include:

1. Root cause — one paragraph from local analysis
2. Files to modify — exact paths and what changes in each
3. Proposed fix — description of the code changes
4. Regression test plan — what test is added and what it verifies
5. Verification commands — which commands will be run

STOP HERE and wait for user confirmation. Do NOT proceed until the user says yes. This applies even when the root cause looks obvious.

Phase 3: Implement Fix

1. Branch. Never work on main (see the Git Workflow section of CLAUDE.md):

git checkout -b sentry-fix/<issue-id-lowercase>

This checkout is often shared with other sessions. Before branching, run git status --short and confirm the tree is clean — a dirty tree means someone else's work in progress, and carrying it onto your branch (or committing it) has happened before. Never git reset --hard here.

2. Implement the fix:

   • Follow existing code patterns and style
   • Only modify files directly related to the issue
   • No gratuitous refactoring

3. Write a regression test:

   • Rust: #[test] in the relevant module's test section, or a test file in the same directory.
   • React / Expo: a vitest test in the corresponding .test.ts(x), creating one if none exists and following neighbouring test files.
   • iOS: a SwiftPM test under apps/ios/Packages/AMUXCore/Tests/.

   The test must reproduce the scenario that caused the original error.

4. Prove the test catches the bug. Stash or revert the fix, run the new test, and confirm it fails for the expected reason; then restore the fix and confirm it passes. A regression test that was never seen red is not evidence. Use a file copy plus git checkout -- <path> rather than git stash on a shared checkout.

Phase 4: Verify

Run the full suite for the platform, including the test just written — not just the linter:

• React: pnpm test:unit && pnpm typecheck && pnpm lint
• Rust: the rust-cli.js test command above, plus pnpm rust:clippy and cargo fmt --check --manifest-path apps/desktop/Cargo.toml
• Expo: pnpm expo:test && pnpm typecheck:expo
• iOS: pnpm ios:test:core (pnpm ios:test additionally needs a booted simulator; skip it unless the fix is UI-level and say that you did)

Never pipe these through tail/head when you care about the result — the pipeline's exit code is the pager's, so a failure reads as exit 0. Redirect to a file and check $?.

Compare lint output against the pre-change baseline rather than counting warnings in the absolute: this repo carries known warnings, and "0 errors" with an unchanged warning set is the bar.

If verification fails:

1. Read the error output
2. Fix the issue
3. Re-run verification
4. Maximum 2 retry rounds. If still failing, stop and report to the user.

If a failure looks unrelated to the change, check it against the known-flaky and known-broken memories before assuming you caused it — several suites in this repo fail on a clean main for environmental reasons.

Phase 5: Commit, then stop

1. Stage only the files you changed, by explicit path. Never git add -A — an unscoped add on this shared checkout is what put a private document into a public commit once already:

git add <changed-files>
git commit -m "fix(<scope>): <description> (Sentry <ISSUE-ID>)"

<scope> is the module/component (e.g. chat, settings, daemon, editor).

2. Stop here and report back. Per CLAUDE.md, do not git push or run gh pr create on your own initiative, even when everything is green. Wait for an explicit "open the PR" / "ship it" / "提 PR" / "可以提 PR 了".

Report: what was fixed, the verification results (including the red-then-green evidence for the regression test), and anything left unverified.

Phase 6: PR — only when the user asks

git push -u origin sentry-fix/<issue-id-lowercase>
gh pr create --title "fix(<scope>): <short description>" --body "$(cat <<'PREOF'
## Sentry Issue

Fixes [<ISSUE-ID>](<sentry-issue-permalink>)

## Root Cause

<root cause summary from local analysis>

## Fix

<description of code changes>

## Test Coverage

<the regression test, and the failure it produces without the fix>

## Verification

<commands run and their results; name anything not verified and why>
PREOF
)"

State verification honestly in the PR body — if something could not be run, say which and why rather than omitting it.

Constraints

• NEVER modify code before the user confirms the fix plan (Phase 2)
• NEVER modify files unrelated to the issue
• ALWAYS write a regression test, and always see it fail before it passes
• NEVER push or open a PR without an explicit request (Phase 5/6)
• If sentry CLI is not authenticated, prompt the user to run sentry auth login
• If gh CLI is not authenticated, prompt the user to run gh auth login