{ "schema_version": 1, "type": "skill", "slug": "bug-filing", "title": "bug filing", "brief": "Standard format and channels for filing bugs in the Adom ecosystem. Where each bug type lives (Colby list, GitHub issues, gchat), what info to include, and which fields are mandatory.", "version": "1.0.0", "tags": [], "license": "MIT", "sample_prompts": [ { "label": "File a bug", "prompt": "File a bug for the chipfit lint regression I just hit" }, { "label": "Colby list", "prompt": "Add this to the Colby bug list" }, { "label": "Bug channel", "prompt": "Where do I file an adom-tsci bug?" }, { "label": "Issue template", "prompt": "What template should I use for an Adom platform bug?" }, { "label": "Repro steps", "prompt": "Help me write repro steps for this bug" } ], "source_path": "SKILL.md", "readme": "---\nname: bug-filing\ndescription: 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\".\n---\n\n# Filing GitHub Issues with Visual Mockups\n\nHow 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.\n\n## When to use this\n\n- Filing a bug where the problem is visual (wrong layout, bad UX flow)\n- Proposing a UI/UX change with before/after mockups\n- Any GitHub issue that needs screenshots to explain the problem\n\n## The workflow\n\n### 1. Capture the current state\n\nScreenshot the actual UI showing the problem:\n\n```bash\n# Hydrogen panels\nadom-cli hydrogen screenshot screen -o /tmp/current-state.png\n\n# Desktop app windows\nadom-desktop desktop_screenshot_window '{\"hwnd\": }'\n\n# Full desktop\nadom-desktop desktop_screenshot_screen\n```\n\n#### If the user already pasted a screenshot into chat\n\n**Do NOT substitute a fresh capture.** A \"similar\" screenshot is not the\nscreenshot -- it loses the specific moment, state, error, or overflow the\nuser wanted to show. Bridge their pasted image to a real file via\nshotlog. See `adom-screenshot` SKILL.md (\"When the user pastes a\nscreenshot directly into Claude chat\") for the full flow:\n\n1. `shotlog open --channel `\n2. Tell the user: \"Paste your screenshot (Ctrl+V) into the Shotlog tab\"\n3. Pick up the file from `~/project/screenshots/shotlog//`\n4. Upload to the GH issue's repo at `.github/issue-assets/.png` via\n `gh api repos///contents/...` and embed in the issue\n body.\n\n### 2. Find exact element positions\n\n**Never guess pixel positions.** Use DOM queries:\n\n```js\n// Get exact coordinates of any HTML element\ndocument.querySelector('.target-button').getBoundingClientRect()\n// -> {x: 1342, y: 58, width: 32, height: 32}\n```\n\nIf you can't query the DOM (browser chrome, native app), use the inject+compare technique:\n1. Screenshot base state\n2. Inject CSS borders: `element.style.border = \"3px solid red\"`\n3. Screenshot again\n4. Compare to find exact positions\n\n### 3. Create annotated screenshots with Pillow\n\n```python\nfrom PIL import Image, ImageDraw, ImageFont\n\nimg = Image.open('/tmp/current-state.png')\nd = ImageDraw.Draw(img)\n\n# Red outlines on problem areas\nd.rectangle([x1, y1, x2, y2], outline=(248, 81, 73), width=3)\n\n# SOLID callout boxes (never transparent - bleed-through confuses the viewer)\nd.rectangle([x, y, x+w, y+h], fill=(13, 17, 23), outline=(248, 81, 73), width=2)\nd.text((x+8, y+4), 'Problem description', fill=(248, 81, 73), font=font)\n\n# Bottom annotation strip for summary\nd.rectangle([0, H-70, W, H], fill=(13, 17, 23))\nd.text((20, H-64), 'PROBLEM 1:', fill=(248, 81, 73), font=font)\n```\n\n**Key rules:**\n- SOLID backgrounds on all overlays. Never transparent.\n- Measure positions from DOM or pixel scanning. Never guess.\n- Use connector lines from outlines down to callout boxes\n- Put callouts in the content area, not overlapping browser chrome\n\n### 4. Create mockup overlays showing proposed UX\n\nOverlay your proposed UI panel on the real screenshot:\n\n```python\n# Solid dark block behind the panel\nd.rectangle([px-10, py-10, px+pw+10, py+ph+10], fill=(13, 17, 23))\n\n# Panel with border\nd.rounded_rectangle([px, py, px+pw, py+ph], radius=12, \n fill=(22, 27, 34), outline=(0, 184, 176), width=2)\n\n# Add a triangle pointing to the UI element it drops from\nd.polygon([(cx, py-8), (cx-10, py), (cx+10, py)], fill=(22, 27, 34))\n```\n\n### 5. Ralph loop via shotlog\n\nAfter EVERY iteration, inject to shotlog so the user can watch your progress:\n\n```bash\nshotlog inject -c bug-mockup -d \"iteration-description\" /tmp/mockup.png\n```\n\nOpen the shotlog viewer so the user sees each iteration:\n```bash\nshotlog open -c bug-mockup\n```\n\n**Never show the user an image you haven't ralph-looped yourself.** Generate it, inject to shotlog, look at it, fix issues, repeat.\n\n### 6. Write the bug with thesis for each image\n\nEvery mockup image needs a thesis explaining the design intent:\n\n```markdown\n## 1. Current Problems (annotated screenshot)\n\n**Thesis:** We know the browser requires X. We're not asking to bypass it.\nBut OUTSIDE of that constraint, the AI should control everything...\n\n![Current problems](url)\n```\n\nThe thesis prevents the reader from getting defensive. Acknowledge constraints upfront, then explain what you're proposing within those constraints.\n\n### 7. Show the complete filing to the user BEFORE filing\n\nCreate an HTML page with all mockups + theses + full bug text. Serve it and show to the user.\n\n**Use a Hydrogen webview tab (default, lightweight):**\n```bash\n# Serve the review page\ncd /tmp/bug-review && python3 -m http.server 8795 &\n\n# ADD A NEW webview tab - never steal an existing one\nadom-cli hydrogen workspace add-tab --panel-id \\\n --panel-type \"adom/a1b2c3d4-0031-4000-a000-000000000031\" \\\n --display-name \"Bug Review\" \\\n --display-icon \"mdi:bug\" \\\n --initial-state '{\"url\":\"https://.adom.cloud/proxy/8795/review.html\"}'\n\n# Activate it\nadom-cli hydrogen workspace active-tab --panel-id --tab-id \n```\n\n**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.\n\n**Use pup only if the user has adom-desktop installed (heavier, separate window):**\n```bash\nadom-desktop browser_open_window '{\"sessionId\":\"review\",\"profile\":\"review\",\"url\":\"https://.adom.cloud/proxy/8795/review.html\"}'\n```\n\nWebview is lighter and available to every user. Pup requires adom-desktop installed on their desktop. Default to webview.\n\n**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.\n\n### 8. Host images on the container\n\nThe Adom container's proxy URLs are public and stable:\n\n```text\nhttps://.adom.cloud/proxy//image.png\n```\n\nUse 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.\n\n**Do NOT upload mockup images to the Adom Wiki** - that pollutes the product page. The wiki is for product content, not bug report assets.\n\nFor permanent GitHub-native hosting, images can be committed to the repo in an `issues/` or `docs/` folder.\n\n### 9. Write clean GitHub-flavored markdown\n\nWrite the bug body as a `.md` file. Do NOT convert from HTML - write markdown directly. Common mistakes:\n\n- **Don't leave HTML tags in markdown.** No `
`, `
`, `
` residue from HTML conversion.\n- **Use triple backtick code blocks** with language hints: ` ```bash `, ` ```json `\n- **Use standard markdown tables**, not HTML tables. GitHub renders both but markdown is cleaner.\n- **Test locally** by reading the .md file yourself before filing.\n\n```bash\n# Write markdown directly to a file\ncat > /tmp/bug.md << 'EOF'\n## The problem\n...\n```bash\nadom-cli hydrogen screenshot screen\n```text\n...\n| Today | Proposed |\n|-------|----------|\n| 5 steps | 1 step |\nEOF\n```\n\n### 10. Get user approval BEFORE filing\n\n**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.\n\n### 11. File the issue\n\n```bash\ngh issue create --repo owner/repo \\\n --title \"Clear, actionable title\" \\\n --body-file /tmp/bug.md\n```\n\n### 12. Give the user the link\n\nAlways give the user the clickable GitHub URL immediately after filing:\n\n```text\nFiled: https://github.com/owner/repo/issues/NNN\n```\n\nDon'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`.\n\n### 13. Compose a gchat message for the developer\n\nAfter filing, the user needs to notify the developer. Write a concise gchat message that includes:\n\n1. **The issue URL** - clickable, so the developer can navigate directly\n2. **One-line summary** of what the issue asks for\n3. **The \"killer example\"** - the single most compelling before/after that makes the developer go \"oh, I get it\"\n4. **Acknowledgment** of any related issues they already fixed\n\nFormat:\n\n```text\nHey [name] - filed a new [repo] issue:\n\n**#NNN - [title]** [url]\n\n[1-2 sentence summary of the ask]. The detailed \"today vs proposed\" \ntable shows [the compelling stat, e.g. \"how 7 API calls collapse to 1\"].\n\n[If applicable: Thanks for knocking out #NNN already!]\n```\n\nExample:\n\n```text\nHey Colby - filed a new Hydrogen issue:\n\n**#289 - Make workspace and sharing APIs AI-friendly**\nhttps://github.com/adom-inc/hydrogen/issues/289\n\nTab names should be the primary key (not UUIDs), blocking wait \ncommands instead of polling, and a one-liner webview open with \n--activate --alert. The \"today vs proposed\" table shows how 7 API \ncalls collapse to 1.\n\nThanks for knocking out #281 already!\n```\n\nKey rules:\n- **Always include the URL.** Don't make them search for it.\n- **Keep it under 5 lines.** They'll read the full issue on GitHub.\n- **Lead with the issue number + title** so it's scannable.\n- **Don't repeat the whole bug.** The gchat is a notification, not a duplicate.\n\n## Common colors for annotations\n\n```python\nRED = (248, 81, 73) # Problems, current issues\nGREEN = (63, 185, 80) # Proposed solutions, success\nTEAL = (0, 184, 176) # Adom brand, accent, AI elements\nWHITE = (230, 237, 243) # Text\nGRAY = (139, 148, 158) # Secondary text\nDARK = (13, 17, 23) # Background (solid, never transparent)\nCARD = (22, 27, 34) # Panel background\nBORDER = (48, 54, 61) # Borders, separators\n```\n\n## Mistakes to avoid\n\n- **Transparent overlays** - text from underneath bleeds through and confuses people\n- **Guessing pixel positions** - query the DOM or measure. Wastes hours otherwise.\n- **Uploading to the wiki** - pollutes the product page. Use container proxy URLs.\n- **Filing without user APPROVAL** - show the filing in a webview, get explicit \"yes\" before posting. NEVER post without approval. Ever.\n- **Using pup for GitHub** - it's unauthenticated Chrome. Give the user a URL to click in their real browser.\n- **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.\n- **Em dashes** - reeks of AI text. Use \" - \" instead.\n- **Skipping shotlog** - the user can't see your ralph loop progress without it\n- **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.\n- **Converting HTML to markdown** - don't convert, write markdown directly. HTML-to-markdown converters leave broken tags everywhere.\n- **Forgetting the issue URL in gchat** - always include the clickable URL. Don't make the developer search.\n- **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.\n- **Using pup for GitHub** - it's unauthenticated Chrome. Give the user a URL to click in their real browser.\n- **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.\n- **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.\n", "author": { "name": "Kyle Bergstedt", "email": "kyle@adom.inc" }, "visibility": { "public": true }, "hero": null, "discovery_triggers": [], "discovery_pitch": null, "metadata": {}, "created_at": "2026-05-28T05:29:38.182Z", "updated_at": "2026-05-28T05:29:38.182Z", "sub_skills": [], "parent_app": null, "org": "adom" }