Przejdź do treści
Biblioteka skilli
DevOps i chmura · Analiza

debug

/debug

Diagnozuje problemy produkcyjne i lokalne, podążając za logami, śladami i metrykami (HTTP, gRPC, async): błędy, skoki opóźnień, odpowiedzi 5xx, naruszenia SLO i regresje w aplikacji z instrumentacją.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
16.07.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 16.07.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Diagnozuje problemy produkcyjne i lokalne, podążając za logami, śladami i metrykami (HTTP, gRPC, async): błędy, skoki opóźnień, odpowiedzi 5xx, naruszenia SLO i regresje w aplikacji z instrumentacją.

Oryginalny opis (EN)

Triage and diagnose production or local issues by following logs → traces → metrics (HTTP/gRPC/async). Use when investigating errors, latency spikes, 5xx responses, SLO violations, or regressions in an instrumented app. NOT for adding new instrumentation (use observability); NOT for applying resilience patterns (use resilience).

Jak działa

  1. Overview
  2. Inputs / Outputs
  3. Workflow
  4. Minimum viable execution
  5. Guardrails
  6. Common failure modes
  7. References
  8. Output Template
Sekcje z nagłówków SKILL.md, w oryginale · 141 linii, 929 słów
Podgląd SKILL.md
---
name: debug
description: "Triage and diagnose production or local issues by following logs → traces → metrics (HTTP/gRPC/async). Use when investigating errors, latency spikes, 5xx responses, SLO violations, or regressions in an instrumented app. NOT for adding new instrumentation (use observability); NOT for applying resilience patterns (use resilience)."
metadata: {"stage":"Harden","tags":["incident-response","triage","logs","tracing","metrics","production-issue","5xx","latency","regression","postmortem"],"aliases":["diagnose","troubleshoot","investigate","triage","incident","production-bug","outage","incident-review"]}
---

# Debug (Log → Trace → Metrics)

## Overview

This skill is for **debugging** with existing telemetry. It does **not** focus on adding instrumentation (use `observability` when telemetry gaps block triage).

Goal: turn “something is broken/slow” into:

- a concrete **symptom + impact** statement,
- an **evidence-backed hypothesis** (or a small set of competing ones),
- a **mitigation** (rollback/flag/scale) when needed,
- a short list of **fix + follow-up** tasks.

## Inputs / Outputs

**Inputs**: Symptom description (what's failing/slow); access to logs, traces, and metrics; environment and time window.
**Outputs**: Root cause diagnosis with evidence, mitigation action, fix plan, learning capture. Feeds follow-ups to `observability`, `resilience`, `platform`, or `architecture`.

## Workflow

### 0) Establish ground truth (2–5 minutes)

Capture:

- Environment (`local`/`dev`/`staging`/`prod`) and time window (start/end).
- Symptom (what’s failing/slow) and impact (SLO/user-visible blast radius).
- One **exemplar**: request/trace ID, job run ID, message ID, or timestamped log line.

### 1) Logs (find the exemplar and its correlation IDs)

1. Find the first error/timeout log line closest to the symptom window.
2. Identify correlation keys (prefer stable IDs):
   - `traceId`, `requestId`, `spanId`
   - `op` (route template / RPC method / job name / message type)
   - error code/type (typed error envelope, gRPC status, HTTP status)
3. Pull the **full log story** for the exemplar (start → downstream call(s) → failure).

Copy/paste helpers live in `references/commands.md`.

### 2) Trace (turn the exemplar into a dependency hypothesis)

If you have a `traceId`, use it.

1. Open the trace and confirm the root span matches the suspected operation (`op`).
2. Identify:
   - the slowest span(s),
   - the first error span(s),
   - retries (multiple similar child spans),
   - deadline/time budget signals (deadline exceeded, timeout errors).
3. Convert that to a dependency statement:
   - “`service A` is timing out calling `service B` method `X`”
   - “DB query `Y` is slow / missing index / deadlocked”
   - “Queue consumer is failing on message type `T` (poison message)”

If you cannot find/interpret traces, fall back to logs + metrics and consider adding missing telemetry via `observability`.

### 3) Metrics (confirm blast radius + regression)

Use metrics to answer:

- Is this widespread or isolated to one tenant/route/method?
- Is it a new regression (deploy-correlated) or a gradual degradation (resource/saturation)?
- Is it primarily errors or latency?

Start with RED for the boundary (HTTP route / gRPC method / consumer group).

### 4) Map failure propagation (technical + organizational)

- If this component degrades, what fails next?
- What is likely failing silently (data drift, dropped work, partial writes, stale reads)?
- What is the organizational cascade (handoff queue, approvals, unclear ownership)?

> **GATE**: Failure propagation (step 4) must be mapped before deciding mitigate vs investigate. If you don't know what breaks next, you can't assess the urgency of mitigation.

### 5) Decide: mitigate vs investigate

If impact is high and evidence points to a recent change:

- rollback / disable flag / reduce load / scale critical dependency

If impact is moderate or unclear:

- tighten the hypothesis with 1–2 targeted checks (another exemplar trace, compare two instances, check downstream health)

### 6) Capture learnings (don’t lose the fix)

If you found a systemic gap, capture it:

- missing telemetry field contracts → [`observability`](../observability/SKILL.md)
- retries without idempotency / missing time budgets → [`resilience`](../resilience/SKILL.md)
- repeated boundary logic across services → [`platform`](../platform/SKILL.md)
- cross-service pattern confusion → [`architecture`](../architecture/SKILL.md)

## Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

1. **Establish ground truth** (step 0) — environment, symptom, one exemplar.
2. **Follow log → trace → metrics** (steps 1-3) — this sequence, in this order.
3. **Map failure propagation** (step 4) — what breaks next, what breaks silently.
4. **Capture learning** (step 6) — don't lose the fix; route to the right skill.

Steps that can be cut under pressure: detailed metric blast-radius analysis (step 3 depth), organizational cascade mapping (step 4 breadth).

## Guardrails

- Don’t log secrets/PII while triaging (even “temporarily”).
- Don’t use unbounded IDs as metric labels; use logs/traces for per-entity investigation.
- Don’t add retries as a debugging “fix” without idempotency/dedupe.
- Prefer a small number of exemplars (2–3) over “grep everything forever”.

## Common failure modes

- Jumps straight to reading code instead of following log → trace → metrics — this skips the evidence and leads to hypothesis-driven debugging without data.
- Skips blast radius assessment (step 3-4) — fixes the symptom without knowing what else is affected or failing silently.
- Fixes the immediate symptom without capturing learning (step 6) — the same failure recurs because the systemic gap is never routed to the right skill.
- Checks only one exemplar and generalizes — different exemplars often reveal different failure modes.

## References

- Copy/paste commands: [`references/commands.md`](references/commands.md)
- Scenario checklists (HTTP/gRPC/consumers): [`references/scenarios.md`](references/scenarios.md)
- Retrospective / Postmortem template: [`../references/structured-thinking-templates.md`](../references/structured-thinking-templates.md)
- If telemetry is missing: [`observability`](../observability/SKILL.md)

## Output Template

When using this skill, return:

- **Symptom**: what is failing/slow (include concrete ops: route/method/job/message type).
- **Impact**: who/what is affected and how badly (errors %, latency p95, backlog size).
- **Time window**: start/end and whether it correlates with deploy/config change.
- **Evidence**: exemplar IDs + the key log/trace/metric observations.
- **Hypothesis**: most likely cause + 1 alternative (if applicable).
- **Failure propagation**: what breaks next, what breaks silently, organizational cascade points.
- **Mitigation**: what you did / recommend doing now (rollback/flag/scale).
- **Fix plan**: code/config changes to make it correct and durable.
- **Follow-ups**: telemetry gaps, runbook updates, tests, new invariants.
  - If root cause is systemic, flag for a follow-up retrospective ([`../references/structured-thinking-templates.md`](../references/structured-thinking-templates.md) — Retrospective / Postmortem).
Pliki w paczce (3)
  • SKILL.md 7 KB
  • references/commands.md 4 KB
  • references/scenarios.md 3 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · bricerising/enterprise-software-playbook90Apache-2.0
ericrisco/rsc-harness100MIT
nicsuzor/academicops100MIT
duronext/jig100MIT
drosam/agents100MIT
rizukirr/vibekit100MIT
DingyangLyu/MatClaw100Apache-2.0
Kanevry/session-orchestrator100MIT
kdlbs/kandev100AGPL-3.0

Migawka bazy z 13.11.2026 · wersja paczki 18c8ff44e645 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90observability
    Instrumentuje usługi strukturalnymi logami, metrykami i śladami OpenTelemetry oraz alertami opartymi na SLO i dashboardach.
  • 100monitoring
    Projektuje i prowadzi obserwowalność aplikacji z metrykami, logami, śladami i alertami: definicje SLO, projekt dashboardów, runbooki dla dyżurnych i reagowanie na incydenty.
  • 100monitoring
    Monitoruje wdrożenia Vercel, pomaga debugować problemy produkcyjne, czytać logi i poprawiać obserwowalność aplikacji.
  • 100monitoring
    Monitoruje wdrożenia Vercel, pomaga debugować problemy produkcyjne, czytać logi i poprawiać obserwowalność aplikacji.
  • 100nrinvestigate
    Bada incydenty produkcyjne na danych New Relic: skoki błędów, regresje opóźnień, alerty i zależności, a także wpływ wdrożeń.
  • 90bec-observability
    Projektuje lub przegląda logi, metryki, ślady, korelację, próbkowanie i sygnały SLO usług.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.