# Bug Report

> Use when a defect needs to be filed in a structured, reproducible format. Produces a bug report with an observed-behavior title, environment, numbered steps to reproduce, expected vs. actual, frequency, severity, priority, attachments, related tickets, and workaround. Enforces reproducibility before filing.

- **Type:** Skill
- **Install:** `agentstack add skill-tahirraufkeeyu-software-development-agent-stack-sdas-bug-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tahirraufkeeyu](https://agentstack.voostack.com/s/tahirraufkeeyu)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tahirraufkeeyu](https://github.com/tahirraufkeeyu)
- **Source:** https://github.com/tahirraufkeeyu/software-development-agent-stack--sdas/tree/main/departments/qa/skills/bug-report

## Install

```sh
agentstack add skill-tahirraufkeeyu-software-development-agent-stack-sdas-bug-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## When to use

Invoke this skill when:
- A QA engineer, developer, or user observes a defect.
- Another skill (performance, accessibility, e2e) detects a regression.
- A support escalation needs to be converted into an engineering-ready ticket.

Do NOT use when: the issue is a feature request (use a different intake); the root cause is already known and a fix is in flight (write a PR instead).

## Inputs

- `observation` (required): One-sentence description of what went wrong ("Cart badge count stays at 0 after adding first item").
- `environment` (required):
  - `os`, `browser` or `app_version`, `build` (git SHA or release tag), `device`, `network` (wifi/4g/throttled).
- `steps` (required): Ordered list of user actions, each a single verb phrase.
- `expected` (required): What the user expected.
- `actual` (required): What the user observed.
- `frequency` (required): `always` | `intermittent (N/M)` | `once`.
- `severity` (required): `blocker` | `critical` | `major` | `minor` | `trivial`.
- `priority` (required): `P0` | `P1` | `P2` | `P3`.
- `attachments` (optional): Paths to screenshots, videos, HAR files, console logs.
- `related_tickets` (optional): Issue IDs for related / duplicate / blocked-by tickets.
- `workaround` (optional): If the user found one.

## Outputs

- A Markdown file following `references/bug-report-template.md`, saved to `reports/bugs/-.md`.
- A reproduction verdict: `reproducible` | `intermittent` | `not_reproducible`. Non-reproducible reports are NOT filed; the skill instead returns a checklist of information to collect.
- If the caller has a tracker MCP configured (Jira, Linear, GitHub Issues), a follow-up suggestion to create the ticket with the generated body.

## Tool dependencies

- `Read`, `Write`, `Edit`.
- `references/bug-report-template.md` for the template.
- Optional: tracker MCP (Linear, Jira, GitHub) for filing; this skill only drafts, never files automatically.

## Procedure

1. **Collect.** Validate all required inputs. If any required field is missing, return a targeted question set — do not fabricate.
2. **Attempt reproduction.** If a runnable target is provided (URL + steps), execute the steps (via Playwright MCP or Chrome DevTools MCP) and record the result. If not reproducible after 3 attempts, set verdict `not_reproducible` and list what additional info is needed (network HAR, console log, exact time, user id, feature flags).
3. **Deduplicate.** Grep the bug archive (`reports/bugs/`) and the tracker (if MCP available) for similar titles / stack traces. Surface duplicates.
4. **Assess severity/priority.** Use this rubric:
   - **Blocker:** data loss, security exposure, or a core flow fully broken.
   - **Critical:** core flow broken with no workaround.
   - **Major:** core flow degraded or secondary flow broken.
   - **Minor:** cosmetic, non-blocking.
   - **Trivial:** typo, spacing.
   Priority combines severity with reach (users affected) and revenue impact.
5. **Fill the template.** Copy `references/bug-report-template.md` and populate.
6. **Attach evidence.** Link screenshots/HAR/logs; verify paths exist.
7. **Suggest workaround.** If one exists or can be derived from the steps, include it.
8. **Return.** The Markdown file path and a one-line summary.

## Examples

### Example 1 — Reproducible cart bug

Input:
```json
{
  "observation": "Cart badge count stays at 0 after adding first item",
  "environment": {"os": "macOS 15.3", "browser": "Chrome 133", "build": "shop@2026.04.19-rc3", "device": "MacBook Pro 14 M3", "network": "wifi"},
  "steps": ["Open /products/blue-hoodie", "Click 'Add to cart'", "Observe header cart badge"],
  "expected": "Badge shows '1'",
  "actual": "Badge shows '0'; cart drawer shows the item correctly on open",
  "frequency": "always",
  "severity": "major",
  "priority": "P1",
  "attachments": ["screenshots/cart-badge-zero.png", "logs/console.log"]
}
```

Generated file `reports/bugs/2026-04-19-cart-badge-stays-at-zero.md` (excerpt):

```
# Cart badge count stays at 0 after adding first item

## Summary
Adding the first item to an empty cart leaves the header badge at 0. The cart drawer lists the item correctly, confirming the POST /api/cart succeeded; only the badge UI fails to update.

## Environment
- OS: macOS 15.3
- Browser: Chrome 133 (stable)
- Build: shop@2026.04.19-rc3 (commit a1b2c3d)
- Device: MacBook Pro 14 M3
- Network: wifi

## Severity: major
## Priority: P1
## Frequency: always (5/5)

## Steps to reproduce
1. Sign out, then open https://staging.shop.example.com/products/blue-hoodie in a clean incognito window.
2. Click the "Add to cart" button (data-testid="product-add-to-cart").
3. Observe the cart badge in the header (data-testid="header-cart-count").

## Expected
Header cart badge displays "1".

## Actual
Header cart badge stays at "0". Opening the cart drawer shows the item, so the POST succeeded; only the badge fails to update. Refreshing the page then shows "1".

## Impact
Users cannot tell an add-to-cart succeeded from the header alone. Likely to cause duplicate adds and cart-abandonment escalations.

## Attachments
- screenshots/cart-badge-zero.png
- logs/console.log  (shows "Warning: state mutation outside store" from cartStore.ts:84)

## Related tickets
- SHOP-1822 (previous badge regression, closed 2026-02-11)

## Workaround
Refresh the page after adding to cart.
```

### Example 2 — Not reproducible

Input: "Checkout page sometimes shows 500" with no steps, no build, no logs.

Skill output:
```
Verdict: not_reproducible

Please provide:
- Exact URL (path + query)
- Build (release tag or git SHA)
- Approximate timestamp (within 5 minutes, timezone)
- User id or session id (so we can find server logs)
- Browser console output and a HAR file
- Feature flags enabled for the session (from /_/flags)
- Steps that preceded the error (including prior page)

Not filing until at least URL + build + timestamp are available.
```

## Constraints

- Never file a bug that cannot be reproduced; return the info-gathering checklist instead.
- Titles must describe **observed behavior**, not hypothesis ("Badge stays at 0" not "State mutation in cart store").
- Steps must be numbered, start with a verb, and each do exactly one thing.
- Never include PII in the report body; scrub emails/names in attachments first.
- Severity and priority are always both present; they measure different things (impact vs. urgency).
- Attachments must be referenced by path; if the path does not resolve, flag it.

## Quality checks

- [ ] Title describes observed behavior, under 80 chars.
- [ ] Environment includes OS, browser/app version, build (SHA or tag), device, network.
- [ ] Steps are numbered and atomic.
- [ ] Expected and Actual are both present and differ materially.
- [ ] Frequency is quantified (e.g. `5/5`, `2/10`, not just "sometimes").
- [ ] Severity + Priority both set.
- [ ] Attachments exist on disk (or are clearly marked "pending").
- [ ] Related tickets grep-checked for duplicates.
- [ ] Workaround present or explicitly marked "none found".

## Source & license

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

- **Author:** [tahirraufkeeyu](https://github.com/tahirraufkeeyu)
- **Source:** [tahirraufkeeyu/software-development-agent-stack--sdas](https://github.com/tahirraufkeeyu/software-development-agent-stack--sdas)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tahirraufkeeyu-software-development-agent-stack-sdas-bug-report
- Seller: https://agentstack.voostack.com/s/tahirraufkeeyu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.