stevesolun/ctx / .agents/skills/diagnosing-bugs
diagnosing-bugs
VerifiedDiagnose hard bugs and performance regressions with reproducible evidence, focused hypotheses, and proportional instrumentation. Use when something is broken, failing, throwing, intermittently wrong, or unexpectedly slow.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| agents/openai.yaml | config | 103 B |
| references/debugging-playbook.md | markdown | 2.3 KB |
| scripts/hitl-loop.template.sh | script | 1.1 KB |
references/debugging-playbook.md
View on GitHub# Debugging playbook
Load the sections that fit the failure. These are options, not mandatory phases.
## Feedback-loop options
- A focused unit, integration, or end-to-end test.
- A CLI or HTTP invocation with fixture input and a precise assertion.
- A browser script that observes relevant DOM, console, or network behavior.
- Replay of a captured request, trace, event stream, or crash artifact.
- A small harness around the affected service or function.
- Property or fuzz testing for input-dependent failures.
- `git bisect run` when the failure appeared between known revisions.
- Differential execution across versions, configurations, or environments.
- A human-assisted script when automation cannot reach the symptom directly.
Prefer a signal that exercises the user's actual symptom. Improve it where
useful by narrowing setup, pinning time or randomness, isolating external state,
or increasing the reproduction rate of intermittent failures.
## Intermittent failures
Measure a baseline reproduction rate. Repetition, controlled concurrency,
stress, or targeted timing changes can make the failure easier to observe.
Preserve seeds, inputs, schedules, and environment details that explain a
successful reproduction.
## Hypotheses and probes
Frame a hypothesis as a prediction:
> If X is the cause, changing or observing Y should produce Z.
Favor probes that distinguish several plausible causes. Debuggers and REPL
inspection often provide cleaner evidence than broad logging. If temporary logs
are appropriate, use a unique searchable prefix and remove them after use.
For performance problems, compare measured baselines and inspect profiles,
query plans, allocation patterns, or revision history before choosing a fix.
## Regression coverage
A useful regression test represents the real failure at a stable seam. Avoid a
shallow test that cannot exercise the failing interaction. When no honest seam
exists, record that architectural limitation and rely on the strongest
available reproduction for verification.
After the fix, consider:
- whether the original symptom is gone;
- whether focused and nearby regression checks pass;
- whether temporary instrumentation and harnesses remain;
- whether the explanation separates observation from inference; and
- whether the same structural weakness is likely to recur.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |