agentsclimarketplace

Debug

Skill bricerising/enterprise-software-playbook/skills/debug

Composable agent skills (playbooks) for building enterprise-grade web services — covering architecture, resilience, testing, security, and observability.

Install
npx -y skills add bricerising/enterprise-software-playbook --skill debug

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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

SKILL.md

7.2 KB, as published. Nobody here has run it

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
  • retries without idempotency / missing time budgets → resilience
  • repeated boundary logic across services → platform
  • cross-service pattern confusion → architecture

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

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.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.