bug-debugging
Investigate reproducible software bugs and identify likely root causes. Includes API debugging. Use when asked to debug crashes, regressions, inconsistent outputs, logic errors, broken endpoints, auth failures, bad payloads, timeouts, or schema mismatches. Do not use for feature planning or code style cleanup.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- bug-debugging
- description
- Investigate reproducible software bugs and identify likely root causes. Includes API debugging. Use when asked to debug crashes, regressions, inconsistent outputs, logic errors, broken endpoints, auth failures, bad payloads, timeouts, or schema mismatches. Do not use for feature planning or code style cleanup.
03 SKILL.md 正文
Bug Debugging
Goal
Find the smallest evidence-backed explanation for a bug.
When to use
- Crash or exception with stack trace
- Regression after recent change
- Inconsistent output between environments
- Logic error producing wrong results
- Flaky test or intermittent failure
When not to use
- Feature planning or design
- Code style cleanup or formatting
- Performance optimization without a specific bug
- Architecture decisions
- Use debugging-and-error-recovery for broader recovery strategies and incident playbooks
Inputs to collect
- Expected behavior
- Actual behavior
- Reproduction steps
- Logs, traces, stack traces
- Relevant files or commits
Process
- Restate expected vs actual behavior.
- Reproduce if possible.
- Narrow the failing layer.
- Form 2 to 3 root-cause hypotheses.
- Rank them by evidence.
- Propose the safest smallest fix.
- Define validation steps.
Failure-mode taxonomy by stack
Node.js
| Failure Mode | Symptoms | First Check |
|---|---|---|
| Unhandled Promise Rejection | Process crashes with UnhandledPromiseRejectionWarning |
Missing .catch() on async calls |
| Memory Leak | RSS grows over time, eventual OOM | process.memoryUsage(), heap snapshot |
| Event Loop Blocking | High latency, timeouts, unresponsive | Sync I/O in hot path, perf_hooks.monitorEventLoopDelay() |
| Module Resolution Failure | MODULE_NOT_FOUND |
Check node_modules, symlinks, monorepo config |
| TypeScript Build Error | Type mismatch at compile time | tsc --noEmit, check tsconfig paths |
Python
| Failure Mode | Symptoms | First Check |
|---|---|---|
| GIL Contention | CPU-bound threads don't parallelize | threading + CPU work → use multiprocessing |
| Import Circular Dependency | ImportError: cannot import name |
Check import order, use TYPE_CHECKING |
| NoneType Error | AttributeError: 'NoneType' has no attribute |
Check return values, add None guards |
| Virtual Env Mismatch | Wrong package version installed | which python, pip list, check .venv |
| Encoding Error | UnicodeDecodeError |
Check file encoding, use errors='replace' |
| Asyncio Never Awaits | Coroutine runs but doesn't execute | Check for missing await, event loop running |
Go
| Failure Mode | Symptoms | First Check |
|---|---|---|
| Goroutine Leak | Memory grows, goroutine count increases | runtime.NumGoroutine(), check channel blocking |
| Channel Deadlock | fatal error: all goroutines are asleep |
Unbuffered channels, missing receivers |
| Nil Pointer Dereference | panic: invalid memory address |
Check error returns, nil checks on interfaces |
| Race Condition | go build -race detects |
Shared state without mutex, use channels |
| Import Cycle | import cycle not allowed |
Restructure packages, use interfaces |
Reproduction time budget
| Bug Type | Reproduction Strategy | Max Time |
|---|---|---|
| UI bug | Screenshot + DOM inspection + CSS diff | 10 min |
| API bug | Request/response capture + wiremock | 15 min |
| Performance bug | Profile → flamegraph → hotspot | 20 min |
| Concurrency bug | Stress test + race detector | 30 min |
| Data bug | DB snapshot + query reproduction | 15 min |
| Environment bug | Docker compose + env diff | 20 min |
Log triage order
- Error logs — exact error message and stack trace
- Warning logs — degraded state indicators
- Request logs — input parameters and timing
- State logs — before/after snapshots
- Metric logs — CPU, memory, latency at time of failure
Rollback rules
| Severity | Action | Time Limit |
|---|---|---|
| Critical (production down) | Rollback immediately, investigate after | 5 min |
| High (feature broken) | Rollback if fix > 30 min | 30 min |
| Medium (degraded) | Hotfix if possible, rollback if not | 2 hours |
| Low (cosmetic) | Fix forward, no rollback | Next release |
Bug reproduction from tickets
When reproducing from a bug report or ticket:
- Parse signals: error messages, reproduction steps, affected area.
- Route to appropriate test strategy based on affected area.
- Locate source files and trace the code path.
- Form a clear, testable hypothesis.
- Write a failing test that reproduces the bug.
- Run and classify the result.
Rules
- Do not fix the bug — only reproduce it with a failing test
- Leave test files in place as evidence
- Maximum 3 attempts before declaring UNCONFIRMED
- Hard bailout: requires real API credentials, race conditions, manual UI interaction
Confidence levels
| Level | Criteria |
|---|---|
| CONFIRMED | Test fails consistently, matches hypothesis |
| LIKELY | Test fails but failure mode differs slightly |
| UNCONFIRMED | Cannot trigger the failure |
| SKIPPED | Hard bailout trigger hit |
| ALREADY_FIXED | Bug no longer reproduces |
Reproduction report format
- Ticket ID and title
- Confidence level: CONFIRMED / LIKELY / UNCONFIRMED / SKIPPED / ALREADY_FIXED
- Root cause description
- Location (file, lines, issue)
- Failing test path and description
- Fix hint (pseudocode or approach)
API debugging
When debugging backend API failures:
- Identify endpoint, caller, environment, and auth path.
- Check request shape, headers, params, and payload.
- Check response, logs, and traces.
- Compare behavior with expected contract.
- Determine failing layer.
- Recommend fix and verification steps.
API failure modes
| Failure Mode | Symptoms | First Check |
|---|---|---|
| Auth failure | 401/403, token expired | Check token expiry, scopes, audience |
| Schema mismatch | 400/422, validation error | Check request/response schema vs contract |
| Timeout | Request hangs, 504 | Check upstream latency, connection pool |
| Rate limiting | 429, quota exceeded | Check rate limit headers, backoff strategy |
| Upstream failure | 502/503, dependency error | Check dependency health, circuit breaker |
Output format
- Summary
- Reproduction
- Root cause
- Evidence
- Fix
- Validation
04 同仓库更多 Skills
invoice-organizer
Automatically organizes invoices and receipts for tax preparation by reading messy files, extracting key information, renaming them consistently, and sorting them into logical folders. Turns hours of manual bookkeeping into minutes of automated organization.
file-organizer
Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.
developer-growth-analysis
Analyzes your recent Claude Code chat history to identify coding patterns, development gaps, and areas for improvement, curates relevant learning resources from HackerNews, and automatically sends a personalized growth report to your Slack DMs.
connect
暂无简介
twitter-algorithm-optimizer
暂无简介
tailored-resume-generator
暂无简介