systematic-debugging

Diagnose tool errors and unexpected results through a five-step evidence-based debugging workflow.

24|7|Updated Apr 20, 2026
One-click install
npx skills add https://github.com/qiaolei227/opendeploy --skill systematic-debugging-qiaolei227
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/qiaolei227/opendeploy/tree/main/knowledge/skills/common/systematic-debugging
Command: npx skills add https://github.com/qiaolei227/opendeploy --skill systematic-debugging-qiaolei227

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an AI agent hits a tool error, an unexpected query result, or a change that silently fails to take effect, it often falls into guess-and-retry loops that waste time and corrupt state. This Skill enforces a disciplined debugging process so every fix is grounded in verified evidence rather than speculation. ## Core Features & Use Cases - Five-step discipline: List verifiable symptoms, form 2-3 falsifiable hypotheses, gather evidence with read-only tools, lock the root cause, then fix only what the evidence points to. - Anti-pattern guardrails: Explicitly bans blind retries, random field-name changes, and bypass hacks like wrapping errors in conditional checks. - Use Case: A Python plugin registers successfully but the client shows no effect. Instead of re-registering, the agent checks the parent extension FID, inspects the plugin list output, and discovers a typo in the event signature BeforeSave_1, then fixes, re-registers, and verifies. ## Quick Start Load the systematic-debugging skill and walk me through why my plugin registration succeeded but nothing shows up in the client.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I debug a plugin that registered successfully but does not work?▼

First state the symptom precisely, then form two or three falsifiable hypotheses such as a wrong parent extension ID, a malformed event signature, or a client cache issue. Verify each with read-only queries before changing anything, then fix only the confirmed root cause and re-verify.

What is a systematic debugging workflow for AI agents?▼

It is a five-step process: list verifiable symptoms, write down two to three falsifiable hypotheses, gather evidence one hypothesis at a time using read-only tools, lock a single root cause, and then apply a targeted fix followed by verification.

Why does my query return empty results when data exists in the system?▼

Empty results usually come from a wrong object identifier, a mismatched extension ID, or a rolled-back transaction. Check the exact identifiers you passed against list queries and confirm the record exists with a direct read before assuming the tool is broken.

When should I stop retrying a failed tool call?▼

Stop immediately when a tool returns an error, results contradict expectations, or the same operation behaves inconsistently twice. Retrying without a formed hypothesis is an anti-pattern; switch to evidence gathering with read-only tools first.

What should I do when all debugging hypotheses are ruled out?▼

Return to refining the symptom description or generating new hypotheses rather than guessing. If still stuck, honestly report which hypotheses were excluded and suggest concrete external checks such as client or server logs.