Skip to content
Skills Library
DevOps & cloud · Analysis

debug

/debug

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).

Licence
Apache-2.0
Last repository change
16.07.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.07.2026, without references to retired models or APIs.

Licence

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

What it does and when to use it

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).

Original author 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).

How it works

  1. Overview
  2. Inputs / Outputs
  3. Workflow
  4. Minimum viable execution
  5. Guardrails
  6. Common failure modes
  7. References
  8. Output Template
Original SKILL.md headings · 141 lines, 929 words
SKILL.md preview
---
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).
Files in this package (3)
  • SKILL.md 7 KB
  • references/commands.md 4 KB
  • references/scenarios.md 3 KB

Versions

RepositoryScoreLicence
This page · 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

Database snapshot: 13.11.2026 · package version 18c8ff44e645 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90observability
    Instrument services with structured logs, metrics, traces (OpenTelemetry), SLO-based alerts and dashboards. Use when adding monitoring, debugging production, designing alerts, or making a service operable.
  • 100monitoring
    Design and operate application observability with metrics, logs, traces, and alerts. Use for SLO definition, dashboard design, on-call runbooks, and incident response.
  • 100monitoring
    Monitor Vercel deployments, debug production issues, check logs, and understand logging patterns. Use when investigating errors, checking deployment logs, debugging failures, or improving observability.
  • 100monitoring
    Monitor Vercel deployments, debug production issues, check logs, and understand logging patterns. Use when investigating errors, checking deployment logs, debugging failures, or improving observability.
  • 100nrinvestigate
    Investigates production incidents with New Relic data, covering error spikes, latency regressions, open alerts and issues, bad deployments, and failing dependencies, using the `newrelic` MCP tools. Use when the user asks why a service is slow or erroring, what is alerting,…
  • 90bec-observability
    Use when Service logs, metrics, traces, correlation, cardinality, sampling, SLO signals or diagnostic instrumentation need design or review.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.