hnh-report-sentry

name

hnh-report-sentry

description

Investigate a Sentry issue by fetching full error context (stacktraces, events, tags, frequency) and exploring the local codebase to understand root cause. Generates a prioritized report with suggested fixes and offers to create a Jira ticket. Use this skill whenever the user shares a Sentry issue URL, mentions a Sentry error, asks to investigate/debug/triage a production error, or wants to understand why something is failing in Sentry — even if they don't say "Sentry" explicitly but share a link from a Sentry domain.

Sentry Issue Report

Investigate a Sentry issue end-to-end: fetch the error data, explore the codebase to understand the root cause, and produce a prioritized report with concrete fix suggestions.

Input Parsing

Accept any of these formats:

• Full URL: https://{sentry-host}/organizations/{org}/issues/{issue_id}/
• Short URL: https://{sentry-host}/issues/{issue_id}/
• Just an issue ID: 1234567890 (if Sentry context is clear)

Extract: issue_id. The Sentry org and host come from credentials.

Credential Reference

Tokens are in ~/.zshrc — read the file and inline literal values in commands. Never use $ENV_VAR syntax or source ~/.zshrc.

Service	Env vars
Sentry	SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_URL
Jira	JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN

Execution Flow

Phase 1: Resolve the Issue

Parse the Sentry URL to extract the issue ID. Read ~/.zshrc to get SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_URL.

Quick-fetch the issue metadata to identify the project:

curl -s -H "Authorization: Bearer <SENTRY_AUTH_TOKEN>" \
  "<SENTRY_URL>/api/0/issues/<issue_id>/" | python3 -m json.tool

From the response, extract:

• project.slug — needed to resolve the local codebase path
• title, culprit, count, userCount, firstSeen, lastSeen, status
• shortId — the human-readable issue ID (e.g., PROJ-ABC)

Then ask the user which local repo path corresponds to this project slug, unless it's obvious from the conversation context.

Phase 2: Parallel Investigation

Launch both agents in parallel (same tool-call turn). Read each agent's .md file from this skill's agents/ directory and pass its contents as the agent prompt, along with the issue context.

Agent	File	What it does
A: Sentry Fetcher	agents/sentry-fetcher.md	Fetch events, stacktraces, tags, breadcrumbs, frequency data
B: Codebase Explorer	agents/codebase-explorer.md	Explore the local codebase to understand the error context and suggest fixes

Context to pass to both agents:

• Issue ID, project slug, short ID
• Sentry credentials (literal values)
• Sentry URL and org
• Local repo path and service directory (from service mapping)
• The initial issue metadata from Phase 1

Agent B additionally needs:

• The full output from Agent A (stacktraces, error messages, affected files) — but since they run in parallel, Agent B should independently explore the codebase based on the issue metadata from Phase 1. After both complete, you'll synthesize their findings.

Phase 3: Synthesize & Report

Once both agents return, combine their findings into the report format below.

Priority assessment — assign based on these criteria:

Priority	Criteria
P0	Service down, data loss, security breach, or affecting >50% of users
P1	Core feature broken, high error rate (>1000/day), or affecting paying customers
P2	Significant bug with workaround, moderate error rate (100-1000/day), or degraded experience
P3	Minor bug, low error rate (<100/day), edge case, or cosmetic issue
P4	Noise, expected errors, or already-handled cases that shouldn't be in Sentry

Consider: error frequency, user impact (userCount), whether it's new or recurring, the severity of the failure (crash vs. degraded), and whether there's a workaround.

Report Format

## Sentry Report: {short_id} — {title}

**Issue**: {clickable Sentry URL}
**Project**: {project slug} | **Service**: {service path}
**First seen**: {firstSeen} | **Last seen**: {lastSeen}
**Occurrences**: {count} | **Users affected**: {userCount}
**Status**: {status}

### Priority: {P0-P4}
{1 sentence justification}

### Summary
{2-4 sentences explaining what's happening — the error, when/where it occurs, and the likely impact on users}

### Root Cause Analysis
{What the codebase exploration revealed about why this is happening. Reference specific files and line numbers.}

### Suggested Fixes
{Concrete code changes to fix the issue. Include file paths, line numbers, and code snippets.}

> **Note**: These suggestions were generated by AI analysis and should be reviewed by a developer familiar with the codebase before implementation.

### Additional Context
{Relevant breadcrumbs, tags, environment info, or patterns from the Sentry data that help understand the issue}

Step 4: Offer Jira Ticket Creation

After presenting the report, always ask:

"Would you like me to create a Jira ticket for this? If so, which project key should I use?"

If the user says yes, read ~/.zshrc for Jira credentials and create the ticket:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -u "<JIRA_EMAIL>:<JIRA_API_TOKEN>" \
  "<JIRA_BASE_URL>/rest/api/3/issue" \
  -d '<json_payload>'

Jira ticket content — mirror the report but adapted for a ticket:

{
  "fields": {
    "project": {"key": "<PROJECT_KEY>"},
    "summary": "[Sentry] {short_id}: {title}",
    "issuetype": {"name": "Bug"},
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        // Structured ADF content with:
        // - Sentry link
        // - Occurrence count, users affected, first/last seen
        // - Summary of what's happening
        // - Root cause analysis
        // - Suggested fixes (with AI disclaimer)
      ]
    }
  }
}

Important: In the Jira ticket description, the "Suggested Fixes" section must include a clear disclaimer:

Suggested Fixes (AI-Generated) The following suggestions were generated by automated analysis. They should be reviewed and validated by a developer before implementation. The analysis may not capture all context or constraints.

Use Atlassian Document Format (ADF) for the description. Build the JSON payload carefully — ADF is strict about structure.

After creating the ticket, report the ticket key and URL back to the user.