diagnose

Diagnose bugs and performance regressions using deterministic pass/fail feedback loops.

Updated Jul 2, 2025

Search Tags:#automation #debugging #instrumentation #hypothesis-testing #regression-testing #performance-regression

Ready to run

npx skills add https://github.com/janpeterd/dotfiles --skill diagnose-janpeterd

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: diagnose
Source: https://github.com/janpeterd/dotfiles/tree/main/dot_agents/skills/diagnose
Command: npx skills add https://github.com/janpeterd/dotfiles --skill diagnose-janpeterd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill solves the problem of hard-to-fix bugs and performance regressions by turning messy debugging into a structured, testable investigation loop.

Core Features & Use Cases

Build a feedback loop: Create a fast, deterministic pass/fail signal (tests, scripts, CLI, browser automation, trace replay, or harnesses) so you can reliably drive the investigation.
Reproduce, then hypothesise and instrument: Verify the failure mode, generate 3–5 falsifiable hypotheses, and probe one variable at a time.
Fix with regression protection: Prefer writing a failing regression test before the fix, then confirm cleanup and post-mortem learnings.
Use cases: When a user says “diagnose/debug this,” reports failures/throwing errors, or describes regressions in latency/throughput, especially when root cause is unclear.

Quick Start

Ask the assistant to diagnose your bug or regression by first building an automated feedback loop that produces a reliable failing signal for the reported symptom.

Frequently Asked Questions about diagnose

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

FAQPage Schema

How do I debug a hard bug when the root cause is unclear?▼

To debug a hard bug with an unclear root cause, build a deterministic pass/fail feedback loop using tests or scripts, generate 3–5 falsifiable hypotheses, and probe one variable at a time with targeted instrumentation before applying a fix.

What is the best way to diagnose a performance regression in latency or throughput?▼

Diagnose a performance regression by constructing a deterministic feedback loop, formulating ranked falsifiable hypotheses for the latency or throughput drop, and instrumenting the system to validate predictions one variable at a time before fixing.

How do I structure an investigation loop for reproducing intermittent failures?▼

Structure an investigation loop for intermittent failures by creating a reliable automated signal using CLI fixtures, headless browser assertions, trace replay, or fuzzing to reproduce the symptom, then hypothesize and instrument against that deterministic baseline.

Do I need to write a regression test before fixing a bug?▼

You should write a failing regression test before fixing a bug to lock in the deterministic feedback loop, confirm the fix resolves the failure signal, and prevent future regressions; if test seams are missing, document them explicitly before cleanup.

Can I use bisecting and fuzzing to diagnose throwing errors?▼

You can use bisecting and fuzzing to diagnose throwing errors by incorporating them into a deterministic pass/fail feedback loop, generating falsifiable hypotheses from the reliable failure signal, and targeting the investigation one variable at a time.

When should I not use a disciplined reproduce-to-fix debugging workflow?▼

A disciplined reproduce-to-fix debugging workflow is not suitable when you cannot construct a deterministic pass/fail feedback loop using tests, scripts, CLI fixtures, browser automation, trace replay, harnesses, or bisecting to reliably reproduce the reported symptom.