# Telebugs Investigation

> Use when investigating a specific Telebugs error, debugging a production issue from an error group ID or URL, or performing root cause analysis on a bug report.

- Skill: `zhuravel/telebugs-investigation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuravel/telebugs-investigation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuravel/telebugs-investigation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zhuravel (https://skillmd.com/u/zhuravel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhuravel/telebugs-investigation

---


# Telebugs Error Investigation

Systematic approach to investigating production errors reported in Telebugs.

**REQUIRED:** Use the `telebugs` skill for tool loading, data fetching, and response parsing.

## Phase 1: Data Retrieval

Follow the `telebugs` skill to:

1. Load deferred MCP tools
2. Extract `group_id` from the URL
3. Fetch error group + latest report in parallel
4. Parse the large report response (error details, stack traces, breadcrumbs, metadata)

## Phase 2: Pattern Recognition

After extracting all data, analyze:

- **Occurrence count**: from error group's `occurrences`, `first_seen`, `last_seen`
- **Team notes**: error group notes often contain prior investigation context or merged group history
- **Temporal patterns**: frequency trends, time of day patterns
- **Deployment correlation**: compare `release` hash with recent commits
- **Breadcrumb sequence**: what database operations or job events led to the error?
- **Breadcrumb timing gaps**: large time gaps (10-20s+) between timestamps indicate blocking operations
  (DNS timeout, HTTP timeout, slow query) that are often the actual root cause
- **Related errors**: check for siblings in the same time window

```text
mcp__telebugs__list_error_groups(project_id, status: "open", limit: 10)
mcp__telebugs__search_errors(query: "keyword")
```

## Phase 3: Root Cause Analysis

- **Read source code** from every in-project stack trace frame.
  Never propose fixes without reading the actual code first.
- **Check the full exception chain** — `stack_traces` contains multiple exceptions;
  the top one is often a wrapper, the cause is in later exceptions.
- **Trace the call chain** beyond the stack trace — the stack trace shows where the error
  was raised, but trace backward from the culprit (job class) through service layers
  to find the triggering call.
- **Identify contributing factors**: DNS timeouts, race conditions, unique constraint
  violations, API failures, etc.
- **Determine regression scope**: compare `release` commit hash with `git log`
  to identify when the error was introduced.

## Phase 4: Solution Development

- Provide **specific code fixes** with before/after examples
- Include **defensive programming patterns** to prevent recurrence
- Distinguish **immediate hotfix** vs. comprehensive solution
- Recommend **testing strategies** to validate fixes
- Identify **other code paths** that may have the same vulnerability

## Phase 5: Deliverables

Always present findings in this structure:

1. **Executive Summary** (2-3 sentences)
   What broke, why it broke, and business impact

2. **Technical Analysis**
   - Exact root cause with file path and line number
   - Full exception chain explanation
   - Contributing factors and conditions
   - Breadcrumb timeline leading to the error

3. **Immediate Action Plan**
   - Code changes (before/after, copy-paste ready)
   - New test cases covering the fix
   - Validation steps to confirm the fix works

4. **Long-term Improvements**
   - Architectural changes to prevent recurrence
   - Monitoring and alerting improvements

5. **Risk Assessment**
   - Potential side effects of proposed fixes
   - Other areas that might be affected

6. **Dashboard Link**
   Always include the Telebugs URL: `https://<your-telebugs-host>/errors/{group_id}`

## Common Investigation Mistakes

| Mistake | Fix |
| ------- | --- |
| Only looking at the top exception | Check ALL `stack_traces` entries — the cause chain matters |
| Ignoring error group notes | Notes contain prior investigation context and merged group history |
| Proposing fixes without reading source | Always read the files from the stack trace first |
| Missing the dashboard URL | Always include the Telebugs error group URL |
| Skipping related errors check | Use `list_error_groups` or `search_errors` for siblings |
| Not correlating with releases | Compare `release` hash with `git log` to find regressions |