From Bug Found to Bug Filed: A Bug-Reporter Skill for Claude Code

Part 8 of the "Automating Playwright with Claude Code" series. Our pack from Part 6 catches problems (flaky tests, locator issues); this post adds a Skill that turns a caught problem into a properly filed bug report, using the guardrail patterns from Part 7.

Every Skill we've built so far in this series ends with Claude telling you something's wrong. This post closes that loop: a Skill that takes a failure Claude just found and turns it into a bug report good enough to actually file — with reproduction steps grounded in evidence, not guesswork, thanks to the guardrails from Part 7.

Why a Bug-Reporter Skill Is Worth Building

• The gap between "found" and "filed" is where good bugs get lost. A tester who has to manually write up repro steps after already diagnosing the issue often does a rushed job of it, or skips it entirely.
• Consistency helps triage. A bug report with the same structure every time is faster for a team to triage than one written differently by every reporter.
• It reuses everything you already have. This Skill leans directly on evidence gathered by the flaky-test-debugger Skill from Part 6 — nothing here is written from scratch.
• Guardrails matter even more here. A fabricated repro step in a filed bug wastes a developer's time investigating something that isn't real.

Prerequisites

• Completed Part 6 (the Skill pack) and Part 7 (guardrails) of this series.
• A bug tracker your team actually uses (this post uses GitHub Issues as the example; the same pattern applies to Jira or anything else).

Table of Contents

1. What a Good Bug Report Actually Needs
2. Building the Bug-Reporter Skill
3. Applying Guardrails from Part 7
4. Step-by-Step: From a Flaky Test Finding to a Filed Issue
5. Customizing the Template for Your Tracker
6. Conclusion

Step 1: What a Good Bug Report Actually Needs

Before writing the Skill, it's worth being explicit about the fields a useful bug report has — this becomes the Skill's output template:

• Title — specific and searchable, not "Login broken."
• Steps to reproduce — numbered, exact, based on what was actually observed.
• Expected vs actual result — stated separately, not blended into one sentence.
• Evidence — a snapshot, trace, screenshot, or log line, not a description alone.
• Environment — browser, viewport, environment (staging/prod), and test run ID if available.
• Severity/priority suggestion — a starting point for triage, clearly marked as a suggestion.

Step 2: Building the Bug-Reporter Skill

---
name: playwright-bug-reporter
description: "Turn a test failure or bug found during Playwright testing into"
  a filed bug report. Use whenever the user says a bug was found, asks to
  file an issue, or wants a test failure written up as a report.
---

# Playwright bug reporter

## Process
1. Gather evidence first: the relevant snapshot, trace, or log from the
   failure — never write a report from memory of "what probably happened."
2. Fill out the report using this exact structure:

   **Title**: <component/flow> — <specific symptom>, not a vague summary

   **Steps to Reproduce**:
   1. ...
   2. ...
   3. ...

   **Expected Result**: ...

   **Actual Result**: ...

   **Evidence**: <snapshot excerpt, trace line, or screenshot reference>

   **Environment**: <browser, viewport, env (staging/prod), test run ID>

   **Suggested Severity**: <Critical/High/Medium/Low> — flagged as a
   suggestion for the team to confirm, not a final call.

3. Every reproduction step must come from an action that was actually
   taken and observed during testing — not inferred or assumed.
4. Do not suggest a root cause unless directly asked; a bug report
   documents what happened, not why (that's the flaky-test-debugger
   Skill's job from Part 6).

Step 3: Applying Guardrails from Part 7

This Skill is a perfect candidate for the guardrail patterns from Part 7, since a fabricated bug report is actively harmful — it wastes a developer's time chasing something that isn't real:

## Guardrails
- Never include a reproduction step you did not personally execute and
  observe during this session.
- If evidence for any field is missing (no trace, no screenshot), say
  so explicitly in that field rather than leaving it blank or guessing.
- Do not file the issue automatically — always show the report to the
  user for confirmation first, since only they know if it duplicates
  an existing ticket.

That last line matters: filing directly into a tracker is a good candidate for a human-review gate, not full automation — someone still needs to check for duplicates and confirm it's worth filing.

Step 4: From a Flaky Test Finding to a Filed Issue

Here's the whole loop, start to finish:

This checkout test is failing intermittently — can you check it and file a bug if it's real?

1. playwright-flaky-test-debugger (Part 6) fires first, gathering trace evidence and identifying that the "Place Order" button is being clicked before the cart total finishes updating.
2. Once a real, reproducible issue is confirmed (not just occasional CI flakiness), playwright-bug-reporter fires next, producing:

**Title**: Checkout — "Place Order" clickable before cart total finishes updating

**Steps to Reproduce**:
1. Add two items to cart on the checkout page.
2. Immediately click "Place Order" without waiting for the total to refresh.
3. Observe the order is placed with the pre-update total.

**Expected Result**: "Place Order" should be disabled until the cart total
finishes recalculating.

**Actual Result**: Button remains clickable during the recalculation window,
allowing an order to be placed with a stale total.

**Evidence**: Trace shows `cart-total` element still has `aria-busy="true"`
at the moment of the click event (trace timestamp 00:04.211).

**Environment**: Chromium, 1280x720, staging, run #4821

**Suggested Severity**: High — flagged for team confirmation.

1. Claude shows you this report and waits for confirmation before filing — per the guardrail in Step 3.

Step 5: Customizing the Template for Your Tracker

The template above is tracker-agnostic on purpose. To adapt it:

• GitHub Issues: map directly to a .github/ISSUE_TEMPLATE/bug_report.md structure, so the Skill's output can be pasted straight in.
• Jira: add a step mapping "Suggested Severity" to your project's actual priority field values, since these vary by team.
• Any tracker with required custom fields: list them explicitly in the Skill's ## Process section so nothing gets skipped.

Conclusion

This Skill closes the loop between finding a problem and doing something useful with it — and because it inherits the guardrails from Part 7, the reports it produces are grounded in real evidence rather than a plausible-sounding guess. Combined with Part 6's pack, you now have Skills that catch issues, diagnose them, and write them up in a consistent, reviewable format. Next up, we'll zoom out from individual Skills and map how a set like this covers the full Software Testing Life Cycle.

Would your team's tracker need extra fields beyond this template? Let me know what's missing in the comments!