Practical guide
6 min read
Updated
Turn a bug into a reproducible case
Describe expected and observed behavior, isolate a minimal case, sanitize evidence and verify the correction.
Direct answer
Give exact starting conditions and numbered actions that lead to one observable failure. Separate expected behavior, observed behavior and hypotheses. Reduce the case in a safe copy, share sanitized evidence, and repeat the original steps after the fix.
01
1. Describe one observable failure
Write a title combining a trigger and its visible consequence, such as “Removing one topic clears the remaining selection.” Record what you expected and what actually happened separately. Include the page, application build, browser version, operating system and relevant account role. Avoid real account identifiers when a role or synthetic test account is sufficient.
First preserve the conditions of the failure. Note the starting data, language and whether the session was already signed in. Search existing reports before creating another. Keep distinct failures in separate reports so that fixing one does not hide the others. If the failure is intermittent, record attempts and occurrences instead of calling it always reproducible.
02
2. Reduce without destroying the evidence
Work on a copy or test environment. Remove one optional input, extension or interaction at a time and repeat the same steps. Keep a known failing case alongside each reduced version. The smallest case that no longer fails is not a reproduction; restore the last necessary element and record that boundary.
Compare narrowly: same build with one setting changed, then a separate build comparison if needed. A fresh browser profile can help isolate session-dependent behavior, but do not reset the user’s working profile or delete data to make a report cleaner. If a clean profile does not fail, retain the original conditions and report the difference as a clue.
03
3. Give someone a runnable report
The following fictional report illustrates the format. Replace the placeholder build and environment with your observed values; the counts are an example, not measurements from SkillCodex. Use synthetic data that anyone with access to the test environment can recreate.
Ask another person to follow only the report. If they need an unwritten setup step, add it. A reduced HTML page or small repository can help when permitted, but it must contain the actual triggering behavior and clear launch instructions. A screenshot alone cannot establish the interaction sequence.
Title: Removing Design also removes Testing
Build / browser / OS: [observed versions]
Setup: test reading list; no topics selected
1. Select Design.
2. Select Testing.
3. Activate Remove Design.
Expected: Testing remains selected.
Observed: both topics disappear.
Frequency: 3 of 3 attempts (fictional example)
Evidence: sanitized screenshot after step 3
Cause: unknown04
4. Share only useful, sanitized evidence
If you use Playwright traces, inspect the recorded DOM snapshots and network details: the viewer can expose request and response headers and bodies. A useful debugging archive may therefore also contain sensitive content. Review the artifact itself, not just the screenshot attached to the report.
Attach the shortest excerpt that shows the failure and preserve timestamps or step numbers needed to interpret it. Inspect screenshots, console output and exported network traces before sharing. Remove credentials, cookies, authorization headers, personal messages, customer data and private URLs. Recreate the issue with test data where redaction would obscure it.
Keep a private original only where your team’s access rules allow it; do not paste an entire session export into a public ticket. Say what was removed and whether the artifact is a mock. Use a restricted security reporting channel for a suspected vulnerability. Ordinary bug-report guidance does not grant permission to expose another person’s data.
05
5. Separate timing clues from proven causes
For a suspected asynchronous failure, record request order, response order and the visible state at each relevant point. Repeat with a controlled delay in a test environment. A slow network setting may expose an issue but does not prove that latency caused it; an old response, stale state or a different prerequisite could explain the symptom.
After a fix, rerun the original failing case and a nearby case that already worked. Record the tested build and both outcomes. If you cannot reproduce anymore, report that observation and its limits: one successful attempt does not establish that an intermittent bug is fixed. This procedure narrows evidence; it does not promise a root cause or a production-safe patch.
- Replay the reported steps on the identified fixed build: Testing should remain.
- Remove Testing instead: Design should remain in the nearby control case.
- Repeat an intermittent case and report occurrences out of attempts, including zero.
Keep this
Verify before delivery
- 01A second person can recreate the starting state and follow the steps.
- 02Expected and observed outcomes are separate from suspected causes.
- 03Build, environment and frequency are recorded without secrets.
- 04The original failure and a nearby working case are rerun after the change.
- 05Each reduction retains the triggering behavior and its known failing baseline.
- 06Attachments were inspected for private data and their redactions are documented.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Trace viewer (opens in a new tab)Microsoft / Playwright · DOM snapshots and network headers and bodies available in recorded traces; inspect before sharing.
- Bug Writing Guidelines (opens in a new tab)Mozilla · Precise steps, expected versus observed behavior, reduced cases and build context; Firefox-specific advice needs adaptation.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Turn a bug into a reproducible case” step by step
# Apply the “Turn a bug into a reproducible case” guide in your agent ## Objective Give exact starting conditions and numbered actions that lead to one observable failure. Separate expected behavior, observed behavior and hypotheses. Reduce the case in a safe copy, share sanitized evidence, and repeat the original steps after the fix. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Describe expected and observed behavior, isolate a minimal case, sanitize evidence and verify the correction. - Preserve the correct decisions already in place. ## Guide steps - 1. 1. Describe one observable failure — Write a title combining a trigger and its visible consequence, such as “Removing one topic clears the remaining selection.” Record what you expected and what actually happened separately. Include the page, application build, browser version, operating system and relevant account role. Avoid real account identifiers when a role or synthetic test account is sufficient. - 2. 2. Reduce without destroying the evidence — Work on a copy or test environment. Remove one optional input, extension or interaction at a time and repeat the same steps. Keep a known failing case alongside each reduced version. The smallest case that no longer fails is not a reproduction; restore the last necessary element and record that boundary. - 3. 3. Give someone a runnable report — The following fictional report illustrates the format. Replace the placeholder build and environment with your observed values; the counts are an example, not measurements from SkillCodex. Use synthetic data that anyone with access to the test environment can recreate. - 4. 4. Share only useful, sanitized evidence — If you use Playwright traces, inspect the recorded DOM snapshots and network details: the viewer can expose request and response headers and bodies. A useful debugging archive may therefore also contain sensitive content. Review the artifact itself, not just the screenshot attached to the report. - 5. 5. Separate timing clues from proven causes — For a suspected asynchronous failure, record request order, response order and the visible state at each relevant point. Repeat with a controlled delay in a test environment. A slow network setting may expose an issue but does not prove that latency caused it; an old response, stale state or a different prerequisite could explain the symptom. ## Acceptance criteria — Verify before delivery - A second person can recreate the starting state and follow the steps. - Expected and observed outcomes are separate from suspected causes. - Build, environment and frequency are recorded without secrets. - The original failure and a nearby working case are rerun after the change. - Each reduction retains the triggering behavior and its known failing baseline. - Attachments were inspected for private data and their redactions are documented. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:8b9081543e73bf3b64228fa8afc28be2685ad62bd8c1538f3568f478c5b8d4f3
Diagnose a problem
Diagnose a “Turn a bug into a reproducible case” guide gap
# Diagnose a failed application of the “Turn a bug into a reproducible case” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. 1. Describe one observable failure — Write a title combining a trigger and its visible consequence, such as “Removing one topic clears the remaining selection.” Record what you expected and what actually happened separately. Include the page, application build, browser version, operating system and relevant account role. Avoid real account identifiers when a role or synthetic test account is sufficient. - 2. 2. Reduce without destroying the evidence — Work on a copy or test environment. Remove one optional input, extension or interaction at a time and repeat the same steps. Keep a known failing case alongside each reduced version. The smallest case that no longer fails is not a reproduction; restore the last necessary element and record that boundary. - 3. 3. Give someone a runnable report — The following fictional report illustrates the format. Replace the placeholder build and environment with your observed values; the counts are an example, not measurements from SkillCodex. Use synthetic data that anyone with access to the test environment can recreate. - 4. 4. Share only useful, sanitized evidence — If you use Playwright traces, inspect the recorded DOM snapshots and network details: the viewer can expose request and response headers and bodies. A useful debugging archive may therefore also contain sensitive content. Review the artifact itself, not just the screenshot attached to the report. - 5. 5. Separate timing clues from proven causes — For a suspected asynchronous failure, record request order, response order and the visible state at each relevant point. Repeat with a controlled delay in a test environment. A slow network setting may expose an issue but does not prove that latency caused it; an old response, stale state or a different prerequisite could explain the symptom. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Verify before delivery - A second person can recreate the starting state and follow the steps. - Expected and observed outcomes are separate from suspected causes. - Build, environment and frequency are recorded without secrets. - The original failure and a nearby working case are rerun after the change. - Each reduction retains the triggering behavior and its known failing baseline. - Attachments were inspected for private data and their redactions are documented. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:15d21238c401068d652944de257664ec585af829c18487ff1680395bfec129b4
Pack digest: sha256:8815777bedffc41395102a9cee9972ed8a8eabc428c383aac0e91330a57a2a1e