codyswanngt/parity-sentry-seer

Seer — AI Root-Cause Debugging

Take a failure signal (exception, stack trace, failing test, log excerpt, or a Sentry issue) and drive it to a proven root cause and a proposed fix. This is the Lisa-native reimplementation of the upstream sentry@claude-plugins-official plugin's seer command, rebuilt from scratch so the AI-debugging workflow is available to the Codex, agy, and Copilot runtimes (Cursor loads upstream natively).

The Sentry MCP itself (for pulling live issue data) is re-pointed per agent separately by the parity subsystem — this skill works with or without it. When the MCP is connected, use it to fetch issue details, breadcrumbs, and event context; when it is not, work from the error text the user pastes in.

Drift tracking

Pinned to sentry@[email protected] via synced-from. SDK install & configuration is a separate concern owned by parity-sentry-sdk-setup.

Inputs this handles

• A raw stack trace or exception message.
• A failing test (name + assertion output, or the command to reproduce it).
• A log excerpt or error ID from CloudWatch / project logging.
• A Sentry issue URL or ID (resolve via the Sentry MCP when available).

If the signal is too thin to act on (no message, no location, not reproducible), ask for the one missing thing — the exact error text, the failing command, or a repro step — before guessing.

Workflow

1. Capture & normalize the signal

• Read the full error: type, message, and the complete stack trace.
• Identify the deepest frame that belongs to this codebase (ignore node_modules / stdlib frames) — that file:line is your primary anchor.
• Note the runtime, environment, and any IDs (request id, user id, release).
• If a Sentry issue is referenced and the MCP is connected, fetch the event, breadcrumbs, tags, and first/last-seen + frequency.

2. Reproduce (or pin down why you cannot)

• For a failing test, run it in isolation and read the actual vs. expected:

  bun run test -- <test-file-or-pattern>
  

• For a runtime error, find the smallest command/route/input that triggers it.
• A reliably reproduced failure is the strongest evidence; if it is flaky or environment-only, say so explicitly and treat hypotheses as provisional.

3. Form ranked hypotheses

List 2–4 candidate causes, most likely first, each with the reasoning that makes it plausible and a concrete way to confirm or refute it. Common classes:

• Null/undefined or unexpected shape reaching the failing frame.
• Off-by-one / boundary / empty-collection edge case.
• Async race, unawaited promise, or ordering assumption.
• Contract drift — a caller and callee disagree after a recent change.
• Bad input validation / unhandled external response.
• Config/env divergence (works locally, fails in the target environment).

4. Locate the root cause with evidence

Walk the code to confirm or kill each hypothesis, highest-ranked first:

• Grep/Glob for the failing symbol, message string, and the function in the anchor frame; read the surrounding code, not just the one line.
• Trace the data backward from the failure point to where the bad value originates — the crash site is usually a symptom, not the cause.
• Use git log/git blame on the anchor file to find a correlated recent change:

  git log -n 5 --oneline -- <path/to/anchor/file>
  git blame -L <line>,<line> -- <path/to/anchor/file>
  

• When a value is uncertain, add a temporary strategic log/assert to confirm the actual value, run, observe, then remove it. State the observed value as evidence. (For deeper investigations, the debug-specialist agent owns log-placement and CloudWatch tracing.)

Stop when one hypothesis is proven — you can point to the exact line where the wrong value/behavior originates and explain the mechanism.

5. Propose the fix

• Describe the minimal change that addresses the root cause, not the symptom.
• Prefer fixing where the bad value originates over masking it at the crash site.
• Note any other call sites affected by the same root cause.
• Recommend a regression test that would have caught it (a failing test that the fix turns green) — pair with reproduce-bug / tdd-implementation to land it TDD-style, and codify-verification to lock it in.
• Do not silently broaden scope; if you spot adjacent issues, list them separately as follow-ups.

Output

Report in this shape:

## Signal
<error type/message + anchor frame file:line + repro status>

## Root cause
<the proven cause, in plain English, with the mechanism>

## Evidence
- <file:line> — <what it shows>
- <observed value / test output / blame commit> — <why it confirms the cause>

## Proposed fix
<minimal change, where, and why it addresses the cause not the symptom>

## Regression test
<the test that should be added to prevent recurrence>

## Follow-ups (if any)
<adjacent issues found but out of scope>

Rules

• Do not port or copy upstream plugin code. This is a native reimplementation.
• Prove the cause before proposing a fix — no speculative "try changing this".
• Cite concrete file:line evidence for every claim.
• Remove any temporary debug logging you add before finishing.
• Fix the root cause, not the symptom; flag, don't smuggle in, scope creep.
• Never weaken a test to make it pass, and never use --no-verify.