Turn a bug into a reproducible case

# 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

# 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 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

# 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