# Diagnosing Bugs

> Use when the user asks to diagnose a failure or reports a bug or unexplained slowness.

- Skill: `sreejithraman/diagnosing-bugs` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add sreejithraman/diagnosing-bugs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sreejithraman/diagnosing-bugs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sreejithraman (https://skillmd.com/u/sreejithraman)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/sreejithraman/diagnosing-bugs

---


# Diagnosing Bugs

Build a tight signal for the user's exact symptom, reproduce it, then test
causes and repair. Skip a phase only with an explicit reason; the
artifact-only path below supports diagnosis, not a verified fix.

Resolve glossary paths with [glossary paths](../domain-modeling/references/glossary-paths.md)
before reading or writing domain vocabulary. Read an existing glossary and
relevant ADRs when exploring the affected modules.
Use [Fix Root Causes](../engineering-principles/references/fix-root-causes.md)
for repair ownership and root-cause decisions, and
[Attack the Premise](../engineering-principles/references/attack-the-premise.md)
when successive fixes fail the same check. This skill owns the runnable loop.

## Protect evidence

Read potentially sensitive artifacts through a redacting filter so secrets
become `<REDACTED>` **before tool output enters the conversation**. This applies
to inspection reads as well as final reports. Build commands against environment
variables so credentials stay in the environment. Captures may contain auth
headers; quote only the lines needed for the signal. If redacted evidence is
insufficient, explain what is missing and ask the user.

## Phase 1: Build a feedback loop

Spend the effort needed to make one command catch this bug. For performance
work, read [measurement validity](references/measurement-validity.md) before
building or using a baseline, choosing a fix, or reporting comparisons.

Try these loop forms in roughly this order:

1. A failing unit, integration, or end-to-end test at a seam that reaches the bug.
2. Curl or an HTTP script against a running dev server.
3. A CLI with fixture input and a known-good output comparison.
4. A browser reproduction asserting visible state, DOM, console, or network,
   through the host's browser routing before any standalone driver.
5. Replay of a captured request, payload, or event log through the affected path.
6. A throwaway harness with the minimal system and mocked dependencies.
7. A property or fuzz loop for intermittent wrong output.
8. A bisection harness checking known commit, dataset, or version states.
9. A differential loop comparing versions or configurations on the same input.
10. As a last resort, a human-assisted script based on
    `scripts/hitl-loop.template.sh`, with captured observations returned to you.

### Apple targets

Load the reference matching the evidence needed:

- Runtime behavior, crashes, or suspected hangs:
  [Apple runtime](references/apple-runtime.md).
- Slow launch, hitches, excess CPU, or other measured regressions:
  [Apple performance](references/apple-performance.md). For a hang, classify and
  reproduce it with the runtime reference first; profile when delay needs measurement.
- Growing memory, abandoned objects, retain cycles, or memory-pressure termination:
  [Apple memory](references/apple-memory.md).

These refine this loop. Before launching or controlling a Simulator, follow
[simulator-lifecycle](../simulator-lifecycle/SKILL.md) and the host's device
rules. Reach a physical device through the route in the
[iOS verification guide](../verify/references/ios.md).

### Make the signal tight

Narrow setup and scope, assert the specific symptom, and pin time, random seeds,
filesystem, and network where relevant.

For timing and lifecycle failures, capture starting state, event order, and
active operation identity, including relevant cancellation, replacement, and
completion timing. Use [Model the Domain](../engineering-principles/references/model-the-domain.md#stateful-behavior)
when repairing invalid states or transitions.

Phase 1 is complete when you have run one named command and shown its redacted
invocation and output. The command must be:

- **Red-capable:** drive the actual bug path and assert the user's exact symptom,
  with a verdict that can turn red on this bug and green after repair.
- **Deterministic:** the same verdict on repeat. For a flaky failure, raise and
  pin the reproduction rate with repetition, concurrency, stress, or controlled
  timing until it is high enough to debug, and record the observed rate.
- **Short and bounded:** the shortest loop that still reproduces the symptom
  faithfully, with a fixed end. Launch and memory workloads may take minutes.
- **Agent-runnable:** unattended, with human participation only through the HITL template.

Establish this signal before forming a theory. Without it or the matching
artifact below, stop before hypothesising.

### When a runnable loop is unavailable

State what you tried and what prevents reproduction. Ask for access to the
affected environment, a redacted captured artifact (HAR, logs, core dump, or
timestamped recording), or permission for temporary production instrumentation.

An artifact capturing the exact symptom in the affected build supports a
**provisional diagnosis** when it cannot be replayed. Skip Phases 2 and 4;
use Phase 3's ranked falsifiable hypotheses and compare predictions with the
artifact, code, or independent observations. Distinguish supported conclusions
from untested ones. Stay on this diagnosis-only path until a runnable
reproduction exists: Phase 5 and a verified-fix claim require that loop.
Without a matching artifact, stop before hypotheses.

## Phase 2: Reproduce and minimise

Run the loop repeatedly. Confirm it goes red on the user's failure rather than
a nearby bug, and retain the exact error, output, or timing as repair evidence.

When noise in the scenario hides the cause, shrink it one input, caller,
configuration, datum, or step at a time, rerunning after each removal, until
every remaining element is load-bearing: removing it makes the loop green. Keep
the original scenario for final verification. Proceed once the loop reproduces
the failure; the provisional path skips this phase.

## Phase 3: Rank falsifiable hypotheses

Before testing any, rank every hypothesis the evidence still fits; compare
several when more than one fits. For each, name a prediction:
“If X causes this, changing Y will remove the failure or changing Z will worsen it.”
Sharpen or discard a hypothesis without a testable prediction.

Show the ranking to the user before testing so they can supply domain knowledge
or prior exclusions. Continue with that ranking while they are unavailable.

## Phase 4: Probe predictions

Map each probe to a Phase 3 prediction and change one variable at a time.
Prefer debugger or REPL inspection; otherwise place targeted logs at boundaries
that distinguish hypotheses. Tag every temporary log with a unique prefix such
as `[DEBUG-a4f2]` so cleanup can find it. Avoid broad logging.

For performance regressions, establish the baseline with a timing harness,
profiler, or query plan, and measure before fixing; apply the shared
measurement-validity requirements. Bisect when comparing a known-good and a
failing revision would distinguish causes the evidence hasn't settled.

## Phase 5: Fix and add a regression test

Choose a **correct seam**: the regression test must reach the actual failure
and its triggering caller chain, including multiple callers when the bug needs
them. A shallow test that misses the pattern cannot lock down the repair.
Starting from the Phase 2 repro, run the repair through
[tdd](../tdd/SKILL.md)'s red → green cycle at that seam. Temporary probes stay
diagnostic; they are not regression or acceptance tests.

If no correct seam exists, record the architectural limitation for the cleanup
report. In either case, rerun the Phase 1 loop against the original,
unminimised scenario.

## Phase 6: Clean up and report

Finish only when the original repro is green, the regression test passes (or
its missing seam is documented), a repair that affects a user workflow has a
passing [verify](../verify/SKILL.md) verdict, and temporary logs and throwaway
prototypes are removed or the prototypes moved to a clearly marked debug
location. A green diagnostic loop is evidence, not acceptance; `verify` can
reuse matching red evidence from this diagnosis. Search for the unique debug
prefix to confirm removal. State the supported cause in the result and any
commit or PR message.

When evidence establishes a recurring failure class, pass examples and the
verified cause to [correct](../correct/SKILL.md). Historical mining and broader
prevention require that scope from the user; keep active diagnosis focused on
this failure. An isolated incident supports a regression repair, not recurrence.

If the decisive fact required deep investigation, propose the cheapest
persistent signal that would have exposed it earlier: a health check, counter,
or structured log. Name the fact and the signal's runtime and privacy costs.
Implement only within the authorized fix; otherwise report it as a follow-up.
Keep persistent signals distinct from temporary probes.

