AGENT SKILL

runtime-debugging

Diagnose behavior that appears only while a system is running using logs, metrics, traces and health signals, starting with read-only inspection. Use when code inspection cannot explain a live defect or incident.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
runtime-debugging
description
Diagnose behavior that appears only while a system is running using logs, metrics, traces and health signals, starting with read-only inspection. Use when code inspection cannot explain a live defect or incident.

03 SKILL.md 正文

<!-- Generated by Paved plugin paved@2.29.0 from core.debugging.runtime-debugging@0.1.1; edit Paved Core instead. -->

Runtime debugging

When to use

During incidents, and during bug work when the defect cannot be reproduced locally or depends on the environment (data, configuration, load, timing).

Required context

Which environment, which component, and when the behavior was seen. Useful: the integrations context (what the component talks to) and the observability tools the project declares in .paved/tools/.

Preconditions

  • You have been granted access to the environment by a human, for this purpose.
  • You know whether the environment is shared or production. If unsure, treat it as production.

Procedure

  1. Frame the question: what exactly is unexplained, in which time window.
  2. Read before touching. Start with signals that change nothing: logs around the time window, metrics, traces, health and version endpoints, the deployed configuration. Confirm which revision is actually running before comparing with code.
  3. Correlate. Line up the symptom with deploys, configuration changes, traffic, dependency failures. A correlation is a lead, not a cause.
  4. Narrow down with more specific reads: filter by request, identifier or node.
  5. Add observation only if reading is not enough, and only in a way a human approved: a temporary log level, a diagnostic flag. Write down how to undo it before doing it.
  6. Never restart, redeploy, change data, clear caches or run load against a shared or production environment without explicit human confirmation for that action.
  7. Hand findings back: the observations, their sources and time windows. Confirming a cause is the job of the calling skill.
  8. Undo every temporary change from step 5 and record that you did.

Tools

None from the Core. Observability tools differ per project; use those declared in .paved/tools/ or supplied by adapters, and respect their safety class.

Rules

core.quality.unknowns-stay-unknown: a correlation in step 3 is reported as such. core.security.no-secrets-in-source: logs and configuration often contain secrets and personal data; quote only what the finding needs, redacted.

Verification

Required: runtime — the observation was made on the running system, with its source.

Evidence

Log excerpts or metric readings with their source, environment, time window and the revision running there, redacted.

Completion criteria

  • The unexplained behavior is explained by observations, or narrowed down with the remaining unknowns listed.
  • Every temporary change is undone.

Failure modes

Failure Signal Response
Wrong revision Code read does not match what is deployed Confirm the running revision first
Destructive shortcut A restart or data fix is tempting Stop; ask a human
Leaked data Evidence contains secrets or personal data Redact before recording
Correlation taken as cause Conclusion rests on timing alone Report it as a lead

References

None.

Paved integration

Use the project-local Paved contract as the source of truth. Discover state with node "${CLAUDE_PLUGIN_ROOT}/scripts/paved.mjs" status --json, load only relevant .paved/project/ context, and invoke verification with node "${CLAUDE_PLUGIN_ROOT}/scripts/paved.mjs" verify --json. Always run it from the repository being worked on, never from the plugin directory. Do not edit generated integration files or bypass Paved lifecycle and ownership checks.

04 同仓库更多 Skills