# Diagnose

Disciplined diagnosis loop for hard bugs and performance regressions.

- Repository: https://github.com/AvdLee/RocketSimApp (812 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-10-31
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add AvdLee/RocketSimApp --skill diagnose -g -a claude-code -y`
Codex: `npx skills add AvdLee/RocketSimApp --skill diagnose -g -a codex -y`
Cursor: `npx skills add AvdLee/RocketSimApp --skill diagnose -g -a cursor -y`
Gemini CLI: `npx skills add AvdLee/RocketSimApp --skill diagnose -g -a gemini-cli -y`

## Description

Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Diagnose

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

## Phase 1, Build a feedback loop

**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause, bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.

Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**

### Ways to construct one, try them in roughly this order

1. **Failing test** at whatever seam reaches the bug, unit, integration, e2e.
2. **Curl / HTTP script** against a running dev server.
3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
4. **Headless browser script** (Playwright / Puppeteer), drives the UI, asserts on DOM/console/network.
5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.

The rest: https://github.com/AvdLee/RocketSimApp/blob/HEAD/docs/.agents/skills/diagnose/SKILL.md