Overview Files Versions Dependencies Discussions Activity

skill / bug-filing

name: bug-filing
description: Use when filing a bug report or feature request on GitHub that needs screenshots, mockups, or visual explanations. Covers the full workflow from identifying a UX problem to filing a polished GitHub issue with annotated screenshots and mockup overlays. Trigger on "file a bug", "create an issue", "report a bug", "feature request with mockups", "file github issue".

Filing GitHub Issues with Visual Mockups

How to file polished bug reports with annotated screenshots, mockup overlays, and visual proposals. This is the workflow for when you need to show someone a UX problem AND your proposed solution.

When to use this

Filing a bug where the problem is visual (wrong layout, bad UX flow)
Proposing a UI/UX change with before/after mockups
Any GitHub issue that needs screenshots to explain the problem

The workflow

1. Capture the current state

Screenshot the actual UI showing the problem:

# Hydrogen panels
adom-cli hydrogen screenshot screen -o /tmp/current-state.png

# Desktop app windows
adom-desktop desktop_screenshot_window '{"hwnd": <HWND>}'

# Full desktop
adom-desktop desktop_screenshot_screen

If the user already pasted a screenshot into chat

Do NOT substitute a fresh capture. A "similar" screenshot is not the
screenshot -- it loses the specific moment, state, error, or overflow the
user wanted to show. Bridge their pasted image to a real file via
shotlog. See adom-screenshot SKILL.md ("When the user pastes a
screenshot directly into Claude chat") for the full flow:

shotlog open --channel <bug-name>
Tell the user: "Paste your screenshot (Ctrl+V) into the Shotlog tab"
Pick up the file from ~/project/screenshots/shotlog/<channel>/
Upload to the GH issue's repo at .github/issue-assets/<name>.png via
gh api repos/<owner>/<repo>/contents/... and embed in the issue
body.

2. Find exact element positions

Never guess pixel positions. Use DOM queries:

// Get exact coordinates of any HTML element
document.querySelector('.target-button').getBoundingClientRect()
// -> {x: 1342, y: 58, width: 32, height: 32}

If you can't query the DOM (browser chrome, native app), use the inject+compare technique:

Screenshot base state
Inject CSS borders: element.style.border = "3px solid red"
Screenshot again
Compare to find exact positions

3. Create annotated screenshots with Pillow

from PIL import Image, ImageDraw, ImageFont

img = Image.open('/tmp/current-state.png')
d = ImageDraw.Draw(img)

# Red outlines on problem areas
d.rectangle([x1, y1, x2, y2], outline=(248, 81, 73), width=3)

# SOLID callout boxes (never transparent - bleed-through confuses the viewer)
d.rectangle([x, y, x+w, y+h], fill=(13, 17, 23), outline=(248, 81, 73), width=2)
d.text((x+8, y+4), 'Problem description', fill=(248, 81, 73), font=font)

# Bottom annotation strip for summary
d.rectangle([0, H-70, W, H], fill=(13, 17, 23))
d.text((20, H-64), 'PROBLEM 1:', fill=(248, 81, 73), font=font)

Key rules:

SOLID backgrounds on all overlays. Never transparent.
Measure positions from DOM or pixel scanning. Never guess.
Use connector lines from outlines down to callout boxes
Put callouts in the content area, not overlapping browser chrome

4. Create mockup overlays showing proposed UX

Overlay your proposed UI panel on the real screenshot:

# Solid dark block behind the panel
d.rectangle([px-10, py-10, px+pw+10, py+ph+10], fill=(13, 17, 23))

# Panel with border
d.rounded_rectangle([px, py, px+pw, py+ph], radius=12, 
    fill=(22, 27, 34), outline=(0, 184, 176), width=2)

# Add a triangle pointing to the UI element it drops from
d.polygon([(cx, py-8), (cx-10, py), (cx+10, py)], fill=(22, 27, 34))

5. Ralph loop via shotlog

After EVERY iteration, inject to shotlog so the user can watch your progress:

shotlog inject -c bug-mockup -d "iteration-description" /tmp/mockup.png

Open the shotlog viewer so the user sees each iteration:

shotlog open -c bug-mockup

Never show the user an image you haven't ralph-looped yourself. Generate it, inject to shotlog, look at it, fix issues, repeat.

6. Write the bug with thesis for each image

Every mockup image needs a thesis explaining the design intent:

## 1. Current Problems (annotated screenshot)

**Thesis:** We know the browser requires X. We're not asking to bypass it.
But OUTSIDE of that constraint, the AI should control everything...

![Current problems](url)

The thesis prevents the reader from getting defensive. Acknowledge constraints upfront, then explain what you're proposing within those constraints.

7. Show the complete filing to the user BEFORE filing

Create an HTML page with all mockups + theses + full bug text. Serve it and show to the user.

Use a Hydrogen webview tab (default, lightweight):

# Serve the review page
cd /tmp/bug-review && python3 -m http.server 8795 &

# ADD A NEW webview tab - never steal an existing one
adom-cli hydrogen workspace add-tab --panel-id <leaf-id> \
  --panel-type "adom/a1b2c3d4-0031-4000-a000-000000000031" \
  --display-name "Bug Review" \
  --display-icon "mdi:bug" \
  --initial-state '{"url":"https://<slug>.adom.cloud/proxy/8795/review.html"}'

# Activate it
adom-cli hydrogen workspace active-tab --panel-id <leaf-id> --tab-id <new-tab-id>

NEVER navigate an existing webview tab to your content. Check what's in the tab first - it might be shotlog, a demo, or something the user is actively using. Always add a NEW tab. Remove it when you're done.

Use pup only if the user has adom-desktop installed (heavier, separate window):

adom-desktop browser_open_window '{"sessionId":"review","profile":"review","url":"https://<slug>.adom.cloud/proxy/8795/review.html"}'

Webview is lighter and available to every user. Pup requires adom-desktop installed on their desktop. Default to webview.

NEVER file to GitHub without the user reviewing AND approving first. Show them the complete text + images in a webview. Wait for explicit "yes" or "file it" or "looks good". The user may want to change wording, add context, or kill the whole thing. Filing without approval wastes everyone's time and makes you look like you don't listen.

8. Host images on the container

The Adom container's proxy URLs are public and stable:

https://<slug>.adom.cloud/proxy/<port>/image.png

Use the same temp HTTP server (port 8795) that you used for the review page. The container doesn't restart, so the URLs persist until the bug is resolved.

Do NOT upload mockup images to the Adom Wiki - that pollutes the product page. The wiki is for product content, not bug report assets.

For permanent GitHub-native hosting, images can be committed to the repo in an issues/ or docs/ folder.

9. Write clean GitHub-flavored markdown

Write the bug body as a .md file. Do NOT convert from HTML - write markdown directly. Common mistakes:

Don't leave HTML tags in markdown. No <pre>, <p>, </pre> residue from HTML conversion.
Use triple backtick code blocks with language hints: ```bash, ```json
Use standard markdown tables, not HTML tables. GitHub renders both but markdown is cleaner.
Test locally by reading the .md file yourself before filing.

# Write markdown directly to a file
cat > /tmp/bug.md << 'EOF'
## The problem
...
```bash
adom-cli hydrogen screenshot screen
```text
...
| Today | Proposed |
|-------|----------|
| 5 steps | 1 step |
EOF

10. Get user approval BEFORE filing

11. File the issue

gh issue create --repo owner/repo \
  --title "Clear, actionable title" \
  --body-file /tmp/bug.md

12. Give the user the link

Always give the user the clickable GitHub URL immediately after filing:

Filed: https://github.com/owner/repo/issues/NNN

Don't make them ask for it. Don't just say "filed #289". Give the full URL so they can click it and verify. If the markdown rendering looks broken, fix the .md file and gh issue edit NNN --body-file /tmp/bug.md.

13. Compose a gchat message for the developer

After filing, the user needs to notify the developer. Write a concise gchat message that includes:

The issue URL - clickable, so the developer can navigate directly
One-line summary of what the issue asks for
The "killer example" - the single most compelling before/after that makes the developer go "oh, I get it"
Acknowledgment of any related issues they already fixed

Format:

Hey [name] - filed a new [repo] issue:

**#NNN - [title]** [url]

[1-2 sentence summary of the ask]. The detailed "today vs proposed" 
table shows [the compelling stat, e.g. "how 7 API calls collapse to 1"].

[If applicable: Thanks for knocking out #NNN already!]

Example:

Hey Colby - filed a new Hydrogen issue:

**#289 - Make workspace and sharing APIs AI-friendly**
https://github.com/adom-inc/hydrogen/issues/289

Tab names should be the primary key (not UUIDs), blocking wait 
commands instead of polling, and a one-liner webview open with 
--activate --alert. The "today vs proposed" table shows how 7 API 
calls collapse to 1.

Thanks for knocking out #281 already!

Key rules:

Always include the URL. Don't make them search for it.
Keep it under 5 lines. They'll read the full issue on GitHub.
Lead with the issue number + title so it's scannable.
Don't repeat the whole bug. The gchat is a notification, not a duplicate.

Common colors for annotations

RED = (248, 81, 73)      # Problems, current issues
GREEN = (63, 185, 80)    # Proposed solutions, success
TEAL = (0, 184, 176)     # Adom brand, accent, AI elements
WHITE = (230, 237, 243)  # Text
GRAY = (139, 148, 158)   # Secondary text
DARK = (13, 17, 23)      # Background (solid, never transparent)
CARD = (22, 27, 34)      # Panel background
BORDER = (48, 54, 61)    # Borders, separators

Mistakes to avoid

Transparent overlays - text from underneath bleeds through and confuses people
Guessing pixel positions - query the DOM or measure. Wastes hours otherwise.
Uploading to the wiki - pollutes the product page. Use container proxy URLs.
Filing without user APPROVAL - show the filing in a webview, get explicit "yes" before posting. NEVER post without approval. Ever.
Using pup for GitHub - it's unauthenticated Chrome. Give the user a URL to click in their real browser.
Using pup to preview when webview works - webview is lighter and every user has it. Only use pup if you need a separate window or adom-desktop features.
Em dashes - reeks of AI text. Use " - " instead.
Skipping shotlog - the user can't see your ralph loop progress without it
Stealing existing webview tabs - never navigate someone else's tab (shotlog, demo, etc.) to your content. Always add-tab a new one. Check what owns the tab before touching it.
Converting HTML to markdown - don't convert, write markdown directly. HTML-to-markdown converters leave broken tags everywhere.
Forgetting the issue URL in gchat - always include the clickable URL. Don't make the developer search.
Writing a novel in gchat - gchat is a notification, not a duplicate of the bug. 5 lines max. They'll read the details on GitHub.
Using pup for GitHub - it's unauthenticated Chrome. Give the user a URL to click in their real browser.
Claiming push events work - the AI can't receive WebSocket/SSE events. It's not a long-running process. Only blocking CLI calls work. Don't propose features the AI can't actually use.
Using $TAB_ID when you proposed --name as the key - be consistent. If the proposal says names are the primary key, use names everywhere in the proposal.

bug filing

Not installable via adompkg