From df3f963aeaf27b345dcc81095a4ebf6169f1c32d Mon Sep 17 00:00:00 2001
From: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date: Sat, 29 Nov 2025 18:14:36 +0800
Subject: [PATCH] Initial commit

---
 .claude-plugin/plugin.json         |  13 ++
 README.md                          |   3 +
 commands/debug_production_error.md | 200 ++++++++++++++++++++++++++++
 commands/error_impact_analysis.md  | 175 +++++++++++++++++++++++++
 commands/trace_analysis.md         | 201 +++++++++++++++++++++++++++++
 plugin.lock.json                   |  53 ++++++++
 6 files changed, 645 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 README.md
 create mode 100644 commands/debug_production_error.md
 create mode 100644 commands/error_impact_analysis.md
 create mode 100644 commands/trace_analysis.md
 create mode 100644 plugin.lock.json

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..904c7d7
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,13 @@
+{
+  "name": "catalyst-debugging",
+  "description": "Production error monitoring with Sentry MCP integration. Enable when debugging errors, analyzing stack traces, and investigating incidents. ~20k context tokens when enabled.",
+  "version": "1.0.2",
+  "author": {
+    "name": "Coalesce Labs",
+    "email": "hello@coalesce.dev",
+    "url": "https://github.com/coalesce-labs"
+  },
+  "commands": [
+    "./commands"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a2764b3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# catalyst-debugging
+
+Production error monitoring with Sentry MCP integration. Enable when debugging errors, analyzing stack traces, and investigating incidents. ~20k context tokens when enabled.
diff --git a/commands/debug_production_error.md b/commands/debug_production_error.md
new file mode 100644
index 0000000..5e2b759
--- /dev/null
+++ b/commands/debug_production_error.md
@@ -0,0 +1,200 @@
+---
+description: Debug production errors using Sentry error tracking and analysis
+category: debugging
+tools: Task, TodoWrite
+model: inherit
+version: 1.0.0
+---
+
+# Debug Production Error
+
+Investigate production errors using Sentry's error tracking, stack traces, and context.
+
+## Prerequisites
+
+- Sentry MCP must be enabled (this plugin should be enabled)
+- Environment variables configured:
+  - `SENTRY_AUTH_TOKEN`
+  - `SENTRY_ORG`
+  - `SENTRY_PROJECT`
+
+## Usage
+
+```bash
+/catalyst-dev:debug-production-error <error-description-or-id>
+
+Examples:
+  /catalyst-dev:debug-production-error "TypeError in checkout flow"
+  /catalyst-dev:debug-production-error "ISSUE-123"
+  /catalyst-dev:debug-production-error "errors from last deployment"
+  /catalyst-dev:debug-production-error "unhandled exceptions this week"
+```
+
+## What This Command Does
+
+Uses Sentry MCP tools to:
+
+1. Search for relevant errors
+2. Retrieve stack traces and context
+3. Analyze error patterns and frequency
+4. Identify affected users and environments
+5. Suggest root causes and fixes
+
+## Available Sentry Capabilities
+
+When this plugin is enabled, you have access to ~19 Sentry tools:
+
+**Error Search & Analysis**:
+
+- Search issues by query
+- Filter by status, assignment, date
+- View error trends and patterns
+- Identify new vs recurring errors
+
+**Stack Trace Analysis**:
+
+- Full stack traces with source context
+- Source map resolution
+- Frame-by-frame analysis
+- Variable inspection
+
+**Context & Metadata**:
+
+- User context (who was affected)
+- Environment details
+- Release/deployment information
+- Breadcrumb trail (user actions leading to error)
+
+**Issue Management**:
+
+- Update issue status
+- Assign to team members
+- Link to tickets/PRs
+- Add comments and notes
+
+**Root Cause Analysis** (Seer AI):
+
+- AI-powered root cause identification
+- Code-level explanations
+- Specific fix recommendations
+- Related error patterns
+
+## Example Debugging Sessions
+
+### Investigate Specific Error
+
+```bash
+/catalyst-dev:debug-production-error "Show me details for MYAPP-456 including stack trace and user context"
+```
+
+### Search by Error Type
+
+```bash
+/catalyst-dev:debug-production-error "Find all TypeError exceptions in the last 24 hours"
+```
+
+### Deployment Issues
+
+```bash
+/catalyst-dev:debug-production-error "What new errors appeared after release v2.3.0?"
+```
+
+### High-Impact Errors
+
+```bash
+/catalyst-dev:debug-production-error "Show unresolved errors affecting more than 100 users"
+```
+
+## Output Format
+
+Analysis typically includes:
+
+**Error Overview**:
+
+- Error message and type
+- Frequency and trend
+- First seen / last seen
+- Number of users affected
+
+**Stack Trace**:
+
+- Full call stack
+- Source code context
+- File paths and line numbers
+- Variable values (if available)
+
+**User Context**:
+
+- User ID and properties
+- Browser/device information
+- URL and user actions (breadcrumbs)
+
+**Root Cause** (when Seer analysis available):
+
+- Likely cause explanation
+- Relevant code snippets
+- Specific fix recommendations
+- Related issues
+
+## Advanced Queries
+
+### Filter by Environment
+
+```bash
+/catalyst-dev:debug-production-error "production errors in payment service"
+```
+
+### Time-Based Analysis
+
+```bash
+/catalyst-dev:debug-production-error "spike in errors between 2pm-3pm today"
+```
+
+### User-Specific
+
+```bash
+/catalyst-dev:debug-production-error "errors for user@example.com"
+```
+
+### Integration with Analytics
+
+If you have both plugins enabled:
+
+```bash
+# Enable both
+/plugin enable catalyst-debugging
+/plugin enable catalyst-analytics
+
+# Combined analysis
+> "Show me errors in checkout AND how many users abandoned checkout today"
+```
+
+## Workflow Integration
+
+### With Issue Tracking
+
+After identifying root cause:
+
+```bash
+> "Create a GitHub issue for this error with the stack trace and fix recommendations"
+```
+
+### With Code Changes
+
+After finding the bug:
+
+```bash
+/create-plan "Fix the TypeError in checkout.ts based on Sentry analysis"
+```
+
+## Context Cost
+
+**This plugin adds ~20,670 tokens** to your context window. Disable when debugging is complete:
+
+```bash
+/plugin disable catalyst-debugging
+```
+
+---
+
+**See also**: `/error-impact-analysis`, `/trace-analysis`
diff --git a/commands/error_impact_analysis.md b/commands/error_impact_analysis.md
new file mode 100644
index 0000000..ad9b594
--- /dev/null
+++ b/commands/error_impact_analysis.md
@@ -0,0 +1,175 @@
+---
+description: Analyze the impact and scope of production errors
+category: debugging
+tools: Task, TodoWrite
+model: inherit
+version: 1.0.0
+---
+
+# Error Impact Analysis
+
+Assess the severity, reach, and business impact of production errors.
+
+## Usage
+
+```bash
+/error-impact-analysis <error-or-timeframe>
+
+Examples:
+  /error-impact-analysis "ISSUE-789"
+  /error-impact-analysis "checkout errors last 7 days"
+  /error-impact-analysis "critical errors this week"
+  /error-impact-analysis "impact of recent deployment"
+```
+
+## What This Analyzes
+
+### Quantitative Impact
+
+- Number of occurrences
+- Number of users affected
+- Error rate over time
+- Affected environments/releases
+
+### Qualitative Impact
+
+- Error severity (critical, high, medium, low)
+- Affected user workflows
+- Business function impact (checkout, signup, etc.)
+- User experience degradation
+
+### Trend Analysis
+
+- Is it increasing or decreasing?
+- When did it start?
+- Related to specific release?
+- Correlation with traffic/usage
+
+## Example Analyses
+
+### Single Issue Impact
+
+```bash
+/error-impact-analysis "What's the impact of MYAPP-123? How many users, revenue impact?"
+```
+
+### Category Impact
+
+```bash
+/error-impact-analysis "Overall impact of all payment-related errors this month"
+```
+
+### Release Health
+
+```bash
+/error-impact-analysis "Error impact comparison: current release vs previous release"
+```
+
+### Critical Errors
+
+```bash
+/error-impact-analysis "Show all critical errors and their combined user impact"
+```
+
+## Output Format
+
+Analysis includes:
+
+**Scope**:
+
+- Total occurrences
+- Unique users affected
+- Affected countries/regions
+- Browser/device breakdown
+
+**Severity Assessment**:
+
+- Error frequency
+- User impact score
+- Business criticality
+- Blocking vs non-blocking
+
+**Trends**:
+
+- Occurrence over time (chart/data)
+- Peak times
+- Growth rate
+- Comparison to baseline
+
+**Business Impact**:
+
+- Affected revenue-generating flows
+- Customer support tickets related
+- SLA implications
+- Reputation risk
+
+**Prioritization**:
+
+- Recommendation on urgency
+- Comparison with other errors
+- ROI of fixing
+
+## Integration with Analytics
+
+Enable both plugins for deeper impact analysis:
+
+```bash
+/plugin enable catalyst-debugging
+/plugin enable catalyst-analytics
+
+/error-impact-analysis "How many users who hit error X churned vs users who didn't?"
+```
+
+This combines:
+
+- Sentry error data (who hit the error)
+- PostHog behavior data (did they churn)
+
+## Incident Response Workflow
+
+### 1. Assess Impact
+
+```bash
+/error-impact-analysis "new spike in errors at 3pm"
+```
+
+### 2. Determine Severity
+
+Based on output:
+
+- **Critical**: >1000 users, blocking checkout/signup
+- **High**: >100 users, degraded experience
+- **Medium**: <100 users, minor inconvenience
+- **Low**: <10 users, edge case
+
+### 3. Prioritize Response
+
+```bash
+> "Based on this impact, should we rollback or hotfix?"
+```
+
+### 4. Track Resolution
+
+```bash
+> "After fix, compare error rates before and after"
+```
+
+## Tips for Impact Analysis
+
+1. **Consider timeframe** - "last hour" for incidents, "last week" for trends
+2. **Segment users** - Impact on paid vs free users may differ
+3. **Check related errors** - One root cause may affect multiple error types
+4. **Compare releases** - Pinpoint when impact started
+5. **Business context** - Impact during peak hours is more severe
+
+## Context Cost
+
+Plugin uses ~20k tokens. Disable after analysis:
+
+```bash
+/plugin disable catalyst-debugging
+```
+
+---
+
+**See also**: `/debug-production-error`, `/trace-analysis`
diff --git a/commands/trace_analysis.md b/commands/trace_analysis.md
new file mode 100644
index 0000000..8cf2d5d
--- /dev/null
+++ b/commands/trace_analysis.md
@@ -0,0 +1,201 @@
+---
+description: Analyze distributed traces and performance issues with Sentry
+category: debugging
+tools: Task, TodoWrite
+model: inherit
+version: 1.0.0
+---
+
+# Trace Analysis
+
+Investigate distributed traces, transaction performance, and slow requests using Sentry.
+
+## Usage
+
+```bash
+/trace-analysis <trace-id-or-query>
+
+Examples:
+  /trace-analysis "a4d1aae7216b47ff8117cf4e09ce9d0a"
+  /trace-analysis "slow API requests to /checkout"
+  /trace-analysis "traces with >5 second response time"
+  /trace-analysis "performance issues in payment service"
+```
+
+## What This Analyzes
+
+### Trace Components
+
+- Transaction spans (API calls, DB queries, external services)
+- Timing breakdown per span
+- Parent-child span relationships
+- Span operations and descriptions
+
+### Performance Metrics
+
+- Total transaction duration
+- Time spent in each service
+- Database query performance
+- External API latency
+- Network overhead
+
+### Bottleneck Identification
+
+- Slowest spans in trace
+- Sequential vs parallel operations
+- N+1 query detection
+- Inefficient operations
+
+## Example Analyses
+
+### Specific Trace Investigation
+
+```bash
+/trace-analysis "Analyze trace abc123def456: where's the bottleneck?"
+```
+
+### Performance Pattern
+
+```bash
+/trace-analysis "Why are checkout API requests slow today?"
+```
+
+### Service Comparison
+
+```bash
+/trace-analysis "Compare performance of payment service vs order service"
+```
+
+### Database Performance
+
+```bash
+/trace-analysis "Find traces with slow database queries in user service"
+```
+
+## Output Format
+
+Analysis includes:
+
+**Trace Overview**:
+
+- Transaction name and operation
+- Total duration
+- Timestamp
+- Environment and release
+
+**Span Breakdown**:
+
+```
+Transaction: POST /api/checkout (2.4s)
+├─ Authentication (45ms)
+├─ Database Query: SELECT users (120ms)
+├─ External API: Payment Gateway (1.8s) ⚠️ SLOW
+├─ Database Query: INSERT orders (230ms)
+└─ Email Service (180ms)
+```
+
+**Performance Insights**:
+
+- Slowest operations
+- Time distribution (pie chart/percentages)
+- Parallel vs sequential execution
+- Optimization opportunities
+
+**Recommendations**:
+
+- Cache frequently accessed data
+- Optimize specific queries
+- Implement async processing
+- Add timeouts for external calls
+
+## Advanced Analysis
+
+### Multi-Trace Patterns
+
+```bash
+/trace-analysis "Find common bottlenecks across all slow checkout traces today"
+```
+
+### Service Dependencies
+
+```bash
+/trace-analysis "Map service call chain for failed transactions"
+```
+
+### Error Correlation
+
+```bash
+/trace-analysis "Traces that resulted in errors: what went wrong before?"
+```
+
+## Integration Opportunities
+
+### With Error Debugging
+
+```bash
+# Enable debugging plugin (if not already)
+/plugin enable catalyst-debugging
+
+# Combine trace and error analysis
+> "Show me the trace for the transaction that caused error ISSUE-456"
+```
+
+### With Code Changes
+
+After identifying bottleneck:
+
+```bash
+/create-plan "Optimize the slow payment gateway call identified in trace analysis"
+```
+
+## Performance Optimization Workflow
+
+### 1. Identify Slow Transactions
+
+```bash
+/trace-analysis "transactions with >2s response time in last hour"
+```
+
+### 2. Analyze Bottlenecks
+
+```bash
+> "Drill into the slowest trace: which span is the problem?"
+```
+
+### 3. Root Cause
+
+```bash
+> "Why is the database query taking 800ms?"
+```
+
+### 4. Implement Fix
+
+```bash
+/create-plan "Add database index for user lookups based on trace analysis"
+```
+
+### 5. Verify Improvement
+
+```bash
+> "After deploy, compare trace durations before and after"
+```
+
+## Tips
+
+1. **Start with aggregates** - "slow checkouts" before diving into specific traces
+2. **Look for patterns** - One slow trace might be an outlier, many indicate systemic issue
+3. **Check external dependencies** - Third-party APIs often cause slowdowns
+4. **Consider concurrency** - Sequential operations that could be parallel
+5. **Database queries** - N+1 queries, missing indexes, inefficient queries
+
+## Context Cost
+
+Plugin uses ~20k tokens. Disable after analysis:
+
+```bash
+/plugin disable catalyst-debugging
+```
+
+---
+
+**See also**: `/debug-production-error`, `/error-impact-analysis`
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..195e9f8
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:coalesce-labs/catalyst:plugins/debugging",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "efa5bfd91ef05a51060939423de8d6b0bd4bb609",
+    "treeHash": "e9399760b602fe5ccfb545df9be0316d855224dd02128200a89aa1247a82141e",
+    "generatedAt": "2025-11-28T10:15:41.903039Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "catalyst-debugging",
+    "description": "Production error monitoring with Sentry MCP integration. Enable when debugging errors, analyzing stack traces, and investigating incidents. ~20k context tokens when enabled.",
+    "version": "1.0.2"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "31a4db05cc0683529f8eb06740186fa5126bae6050fa620afcd5d69adb5345ea"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "54ab5b3865b263b732466dabf95aa144ccb89a62189312b7cb9bb83643b57f0b"
+      },
+      {
+        "path": "commands/error_impact_analysis.md",
+        "sha256": "5a9d7468f7e9b7c8e0eceb375330db6867f40f51874af1859f1352efb15881c2"
+      },
+      {
+        "path": "commands/trace_analysis.md",
+        "sha256": "6785162df87b9271a7d709b42b6265b218da4a07a8fec8d6cf17ab997ec6430a"
+      },
+      {
+        "path": "commands/debug_production_error.md",
+        "sha256": "6bb6d26b9d0490e692ebec2209ddfcc6de9ef7e6b49b1882e9d762e599ad9b06"
+      }
+    ],
+    "dirSha256": "e9399760b602fe5ccfb545df9be0316d855224dd02128200a89aa1247a82141e"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file