debug-agent

Identify bug root causes by collecting NDJSON logs and testing hypotheses.

1|Updated Apr 14, 2026
One-click install
npx skills add https://github.com/NeuveAI/perfagent-cli --skill debug-agent-neuveai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-agent
Source: https://github.com/NeuveAI/perfagent-cli/tree/main/.agents/skills/debug-agent
Command: npx skills add https://github.com/NeuveAI/perfagent-cli --skill debug-agent-neuveai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill enables systematic, evidence-based debugging by collecting runtime NDJSON logs, generating hypotheses, instrumenting code, guiding reproducible repro steps, and iterating until the root cause is proven with cited log lines.

Core Features & Use Cases

  • Generate 3-5 precise hypotheses about bugs to cover multiple subsystems.
  • Instrument code with lightweight NDJSON logs to test each hypothesis in parallel.
  • Guide reproducible bug reproduction steps and request user confirmation when ready.
  • Analyze collected logs to confirm or reject hypotheses with cited evidence and iteratively refine instrumentation.
  • Remove instrumentation only after successful verification (or as directed).

Quick Start

Start the debug agent in the background, instrument code with the provided logs, reproduce the bug, and review the NDJSON outputs to identify the root cause.

Frequently Asked Questions about debug-agent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the root cause of a bug using runtime logs?

Finding the root cause of a bug with runtime logs requires generating hypotheses, instrumenting code with NDJSON logs, reproducing the issue, and analyzing collected evidence to verify the exact failure point.

What is evidence-based debugging and how does hypothesis testing work?

Evidence-based debugging uses hypothesis testing to systematically identify failures by generating 3-5 potential root causes, instrumenting code to capture targeted runtime logs, and iteratively confirming or rejecting each hypothesis with cited log evidence.

How do I set up NDJSON instrumentation for web application debugging?

Setting up NDJSON instrumentation for web application debugging requires adding lightweight logging statements to your code, starting a background logging server, and executing reproducible steps to capture structured runtime evidence during the failure.

Can I use structured runtime logs to debug issues across services and APIs?

Structured runtime logs can debug issues across services and APIs by capturing NDJSON outputs during reproducible steps, allowing you to trace complex interactions and verify subsystem failures with cited log lines from your background server.

What is the best way to reproduce a bug and verify the fix?

The best way to reproduce a bug and verify the fix is to define reproducible steps, request user confirmation, collect NDJSON runtime logs during execution, and remove instrumentation only after the root cause is proven and successfully verified.