# How to use this bug report bundle

This directory contains the output of an AI-driven analysis of a narrated screen recording.

## For humans

Open `report.html` in your browser for the interactive UI. The local server (run `python server.py <this-folder>` from the project root, or use the link the tool gave you) serves it at http://localhost:8000/report.html.

The sidebar has a filterable list of bugs with thumbnails. The main panel shows each bug's full details — description, narration quote, annotated screenshot, embedded video clip, optional motion keyframes, and a prose walkthrough.

## For AI agents

Two ways to consume this:

1. **Single-file consumption** → read [`MASTER.md`](MASTER.md). Every bug is inlined with its description, narration, suggested fix, themes, and references to local image/clip files. Themes and priority notes at the top tell you what to tackle first.

2. **Per-bug consumption** → browse [`bugs/<bug_id>/`](bugs/). Each folder is a self-contained packet:
   - `README.md` — markdown bundle for this single bug
   - `bug.json` — structured data
   - `screenshot.png` — annotated frame (red box around affected element — **see disclaimer below**)
   - `screenshot_raw.png` — same frame, no annotations
   - `clip.mp4` — the relevant video clip (with 2s padding either side)
   - `clip_description.md` — detailed prose walkthrough of the clip (so you don't need to watch the video)
   - `omniparser_elements.json` — every UI element the detector found on this screen, with pixel coordinates and confidence
   - `motion/` — additional keyframes when motion is relevant to this bug

   Or download a zip from `downloads/<bug_id>.zip`, or everything from `downloads/all_bugs.zip`.

## ⚠️ About the red box in `screenshot.png`

The red bounding box is generated by a two-stage AI pipeline: OmniParser (a YOLOv8 model) detects all interactive UI elements, then Gemini picks which one corresponds to the bug. **It's correct most of the time but not always.** Common failure modes:

- The actual element is *near* the box rather than inside it
- The box landed on an adjacent element with similar appearance
- For region-type bugs ("the whole header is bloated"), no single element matches and the box is approximate

**When acting on a bug:**
1. The **narration quote** and **`clip_description.md`** describe what's actually wrong — trust those first.
2. Look at the full `screenshot.png`, not just inside the red box.
3. If you need precise coordinates, use `omniparser_elements.json` — it has every detected element's pixel bounding box. You can search by label or pick a different element if our pick was off.

## About `omniparser_elements.json`

Each bug folder has this file with the raw output of the UI element detector run on that bug's keyframe. Format:

```json
{
  "image_width": 2560,
  "image_height": 1440,
  "elements": [
    {"id": 0, "x1": 100.0, "y1": 50.0, "x2": 200.0, "y2": 80.0, "confidence": 0.89},
    ...
  ]
}
```

Coordinates are in **pixel space** (the screenshot's actual dimensions). To convert to the normalized 0-1000 coords used by `bug.json`'s `bounding_boxes`, divide x by `image_width` and y by `image_height`, then multiply by 1000.

If our red box is wrong, scan this list for the right element (often by spatial proximity to where the cursor/narrator was pointing).

## Schema reference

- `severity` — how bad: critical | high | medium | low
- `category` — bug | feature_request | ui_polish | question
- `priority_rank` — tackle order (1 = first). Different from severity; considers cross-cutting impact and dependencies.
- `bounding_boxes` — `[ymin, xmin, ymax, xmax]` normalized 0-1000, pointing at the affected element on `screenshot.png` (**guide only — verify against narration**)
- `motion_keyframes` — additional frames showing motion/state-change, only present when the issue involves motion
- `suggested_fix` — recommended fix; prefixed with `[speculative]` if uncertain

## Recommended workflow for fix automation

1. Read `MASTER.md` end-to-end to absorb themes and priority notes.
2. Group bugs by theme — themes are natural PR boundaries.
3. Within a theme, fix in `priority_rank` order.
4. For each bug:
   - Read `clip_description.md` and the narration quote — these are the ground truth
   - Use `screenshot.png` as a visual aid; the red box is a hint, not gospel
   - If the box looks wrong, consult `omniparser_elements.json` for the full list of detected elements
   - Apply `suggested_fix` or your own judgment
