Sentry Loop

Sentry Loop

Window: $ARGUMENTS (default: 7d)

Triage-then-investigate over the error tracker. The output is knowledge, not fixes: every issue in the window ends the run classified, the few that matter end it root-caused, and the findings live in the work tracker - separably from human-authored work items.

Configuration

Read the current repo's AGENTS.md before filing anything:

• Tracker + label: the Work-item tracking section names the tracker and the label/team that marks loop-generated issues (default label: sentry-loop). Create the label on first use if it doesn't exist.
• Sentry access: use the Sentry MCP (find_organizations once, then search_issues / search_events / get_sentry_resource). If the repo has a docs/mcp-sentry.md, follow it.

No tracker configured → produce the report locally under ./tmp/ and stop before the filing stage.

Stage 1 - Sweep

1. Establish the window: $ARGUMENTS if given, else 7d. Then find the standing loop-report issue (search by the loop label); if its latest run comment is newer than the window start, narrow the window to "since last run" and note that in this run's comment.
2. Pull the volume shape: search_events grouped by project (count(), count_unique(issue)) for the window.
3. Pull the issue list: search_issues per project, sorted by new, for the window - capture id, title, culprit, first/last seen, event count, user count, status.

Stage 2 - Classify

Tag every issue with one value per axis. This table IS the deliverable for most issues - classification is cheap, so nothing is skipped.

• Age: new (first seen in window) / recurring / regressed (previously resolved, seen again).
• Impact: user-impacting (users > 0) / zero-user.
• Nature: real (a defect in our code) / env-noise (dev/staging pollution, infra flakes, third-party outages) / external (browser extensions, network, user-device).
• Cluster: issues sharing one probable root cause (same command, culprit, error string, or release boundary) get one cluster id - a burst of distinct Sentry issues is often one incident. Check event extra data (get_sentry_resource) when titles are generic; the real error string usually lives there.

Stage 3 - Investigate (only what earns it)

Deep-dive a cluster only if it is new AND (user-impacting OR clearly a defect). Everything else stays at classification depth.

Per cluster, hypothesis-first:

1. Read the fullest event (get_sentry_resource): stack, tags (release!), and extra data.
2. Form 2–3 ranked hypotheses before reading code.
3. Trace the stack into the codebase; check git log / git log -S around the release tag and first-seen date - most new issues correlate with a recent change.
4. Conclude with: root cause, confidence, file:line references, introducing change if found, affected users/orgs, and what a fix needs (not the fix).

Independent clusters may be investigated in parallel - dispatch one investigator sub-agent per cluster (the Codex investigator role via the codex skill, or an equivalent read-only agent), each fed the cluster's Sentry ids and the classification context; the orchestrator keeps the table and merges reports.

Stage 4 - File

All loop-generated tracker items carry the loop label. Before creating anything, search the tracker for open loop-labeled issues covering the same fix or the same recurring noise - update those instead of duplicating.

The unit of filing is one PR, not one incident. Every issue the loop creates must be closable by a single PR; its title is the change, imperative ("Guard team deletion when a phone number is assigned"), not the symptom.

1. One issue per fix. If a root cause needs two changes (a revert now and a redo later; a backend guard and a separate UI affordance), that is two issues, cross-linked, each independently shippable. Never start the fix.

   The body is the investigation, not just its verdict. A reader must be able to follow the journey from Sentry to conclusion without re-deriving it. Required sections, in order:

   • Sentry evidence - what the event(s) actually showed: error string, extra data, decisive tags (release, counts, first/last seen, users), linked issue(s).
   • Hypotheses - the ranked candidates formed before reading code.
   • Trace - the path walked (file:line) and what confirmed the winner; the introducing change if found.
   • Ruled out - each discarded hypothesis with the evidence that killed it. An issue with nothing ruled out is a smell (Stage 3 wasn't hypothesis-first).
   • Root cause + confidence - one sentence, and why that confidence.
   • Fix shape - acceptance criteria and the suggested entry point (/create-brief <id> or straight /do for trivial ones).

2. Hygiene findings follow the same rule - each fixable noise source (a dev cron writing to prod Sentry, a dead task type still queued) is its own small PR-sized issue. Noise that isn't ours to fix (third-party, browser extensions) does NOT become an issue; it's recorded in the run report and ignored in Sentry with a reason.

3. One standing loop-report issue (create on first run, then reuse): each run appends a comment with the window, volume shape, the full classification table, links to the issues filed above, and what was left un-investigated and why. The latest comment is the next run's "since" marker. Runs never create per-run report issues - the tracker holds work, not logs.

Stage 5 - Annotate Sentry

Make the triage stick in Sentry so next run's sweep is smaller:

• Root-caused and a fix is already deployed → resolved with a reason comment linking the fix and tracker issue.
• Root-caused but not fixed → leave unresolved; comment the root cause and tracker issue link.
• env-noise / external → ignored (untilEscalating) with a reason comment.

Never resolve an issue whose fix has not shipped - it will re-alert as a regression and poison the age axis.

Boundaries

• Report-only: no code changes, no fixes, no config edits. Fixes go through /create-brief → /do.
• Don't investigate recurring known issues past confirming their tracker item still reflects reality.
• If the window's volume is an order of magnitude above the norm, stop classifying individual issues, say so, and triage the spike itself first.