Diagnosing Bugs

Diagnosing Bugs — Read Only

Determine the root cause and explain it with evidence. End with a proposed fix and regression-test strategy, but do not apply either one.

Non-negotiable boundary

• Treat the project and its environment as read-only.
• Do not create, edit, delete, move, rename, format, or generate files.
• Do not modify source code, tests, fixtures, snapshots, configuration, dependencies, lockfiles, documentation, databases, or external services.
• Do not add logs, breakpoints that persist to disk, feature flags, temporary instrumentation, reproduction scripts, harnesses, or tests.
• Do not run migrations, package installation, write-capable API calls, destructive Git commands, or commands likely to mutate persistent state.
• Do not expose secrets. Configuration inspection may report whether a variable exists, but never print its value.
• If reliable diagnosis requires any write or persistent state change, stop. Explain the exact diagnostic change, its scope, risk, and expected evidence, then wait for explicit user authorization. Authorization to diagnose is not authorization to modify.
• If the user also asks for a fix, finish and report the diagnosis first. Implementation is a separate workflow and requires a separate, explicit go-ahead.

1. Establish the symptom

Restate:

• Expected behavior
• Actual behavior and exact error
• Reproduction conditions
• Affected environment and scope
• Last known good state, if known

Separate observed facts from assumptions. Ask only for information that cannot be obtained through safe, read-only inspection.

2. Inspect safely

Prefer existing evidence and existing feedback loops:

1. Existing focused tests or reproduction commands known not to mutate persistent state
2. Existing logs, stack traces, metrics, profiler output, HAR files, screenshots, and recordings
3. Static code tracing from the symptom back through callers and dependencies
4. Read-only debugger or REPL inspection
5. Read-only Git history, blame, diff, and bisect analysis
6. Existing configuration structure, checking presence only when values may be secret

Before running a command, consider whether it writes caches, snapshots, build artifacts, coverage output, databases, queues, or remote state. If uncertain, do not run it; explain the concern and use another probe or ask for authorization.

Do not invent a new test, script, fixture, trace, or harness. If no adequate feedback loop exists, state that limitation and request an existing artifact or propose a narrowly scoped diagnostic change for separate approval.

3. Reproduce and minimise

Use existing read-only mechanisms to reproduce the user's exact symptom. Confirm that a nearby failure is not being mistaken for the reported bug.

Minimise conceptually or through safe runtime inputs: narrow the relevant request, code path, test selection, log window, time range, or dataset view without changing stored data or project files.

Record:

• The exact command or observation used
• Whether reproduction was deterministic
• The smallest confirmed conditions
• Anything that could not be reproduced

4. Form falsifiable hypotheses

Generate 3–5 ranked hypotheses. For each one, state:

• Supporting evidence
• Contradicting or missing evidence
• A prediction that would distinguish it from the others
• A read-only probe that can test the prediction

Do not anchor on the first plausible explanation. Re-rank hypotheses as evidence changes.

5. Test one variable at a time

Map every probe to a prediction. Prefer:

1. Existing debugger or REPL inspection that leaves no persistent changes
2. Existing logs and metrics at the relevant boundary
3. Static tracing of values, ownership, timing, and error propagation
4. Read-only comparison with a known-good revision or environment
5. Existing performance measurements and query plans that are safe to obtain

Do not add instrumentation. If existing evidence cannot distinguish the remaining hypotheses, stop at the uncertainty boundary and state what evidence is missing.

6. Report; do not repair

Return a concise diagnosis containing:

1. Status — reproduced, partially reproduced, or not reproduced
2. Root cause — the most likely causal chain, not merely the failing line
3. Confidence — high, medium, or low, with the reason
4. Evidence — commands, outputs, traces, and relevant file/line references
5. Ruled out — important alternatives eliminated by evidence
6. Impact — affected behavior and likely blast radius
7. Proposed fix — minimal implementation approach, without editing files
8. Regression coverage — recommended test seam and scenario, without writing the test
9. Open questions — remaining uncertainty and the safest next probe

Never claim the bug is fixed. No fix is applied under this skill.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SuperMalow
• Source: SuperMalow/personal-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.