bug-bash-update
Skill1 starsChanged 9 months agoMITView on GitHub
Update docs/BUG_BASH_GUIDE.md after implementing features or fixing bugs. Adds checklist items for new features, annotates fixes, and verifies fixes in the browser before marking them complete. Triggers on "bug bash update", "update bug bash", "update testing checklist".
In this repository9 other files it gives its agents.
- ci-cd-pipelineSkill
- claudemd-auditorSkill
- docs-consolidatorSkill
- ralphSkill
- refactor-auditSkill
- reflectSkill
- setup-workflowSkill
- skill-reviewerSkill
- smoke-testSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 15 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Read the changed files to understand the scope of the change.
- Distinctive: line 24
If no meaningful changes are detected (e.g., only CI, docs, or config changes with no user-visible impact), report "No bug bash updates …
- Very specific: line 28
Read docs/BUG_BASH_GUIDE.md in full.
- Very specific: line 30
Read the existing section headings in docs/BUG_BASH_GUIDE.md
- Very specific: line 32
Use directory structure and component names as signals (e.g., components/auth/ → an "Authentication" section)
- Distinctive: line 33
If no section matches, check if a new section is warranted for an entirely new feature
- Very specific: line 40
Add - [ ] checklist items to the appropriate section
- Distinctive: line 43
Add 2-5 items per feature, covering the happy path and key edge cases
- Very specific: line 50
If no matching [!] item exists, add a new [x] item describing what was fixed (since it was never tracked as a bug)
- Distinctive: line 53
Only update if user-visible behavior changed
- Distinctive: line 54
If purely internal, report "No bug bash updates needed" and stop
- Very specific: line 63
Read the deployment URL from docs/BUG_BASH_GUIDE.md (look in "Test Environment" or "Prerequisites" section).
- Distinctive: line 64
If no URL is listed, stop and ask the user for the deployed URL.
- Distinctive: line 65
NEVER use localhost. Bug bash verification must happen on a deployed build.
- Distinctive: line 69
Check that the bug behavior is no longer present
- Distinctive: line 70
Check that the correct behavior is now shown
- Very specific: line 78
Leave as [!] FIXED — do NOT mark [x]
- Distinctive: line 89
Never remove existing checklist items — only add or modify status markers
- Distinctive: line 90
Keep checklist items concise but specific enough to be independently testable
- Distinctive: line 91
When adding items for a new feature, look at existing items for style/format consistency
- Distinctive: line 93
If a section doesn't exist for a new feature area, create it following the existing heading hierarchy
- Distinctive: line 94
Always include the PR or commit reference when annotating fixes
- Very specific: line 114
NEVER mark [x] without having taken a browser screenshot confirming the behavior.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Bug Bash Update
Automatically update docs/BUG_BASH_GUIDE.md after completing a task. Adds testable checklist items for new features, annotates bug fixes, and verifies fixes in the browser before marking them as verified.
Key principle: Browser verification is the ultimate test. Code review alone isn't enough to mark something verified.
Workflow
Phase 1: Discover what changed
- Analyze the git diff to understand what changed. Try these in order until one produces results:
git diff --cached(staged changes)git diff main...HEAD(branch diff)git log -1 --format="%H" | xargs git diff HEAD~1(last commit)
- Read the changed files to understand the scope of the change.
- Note the commit prefix (
feat:,fix:,refactor:,docs:,chore:,test:,ci:). - Summarize: what area of the app changed, and what's the user-visible impact?
If no meaningful changes are detected (e.g., only CI, docs, or config changes with no user-visible impact), report "No bug bash updates needed" and stop.
Phase 2: Map changes to BUG_BASH_GUIDE sections
- Read
docs/BUG_BASH_GUIDE.mdin full. - Map changed files to BUG_BASH_GUIDE sections:
- Read the existing section headings in
docs/BUG_BASH_GUIDE.md - Match changed file paths to the section that covers that area of the app
- Use directory structure and component names as signals (e.g.,
components/auth/→ an "Authentication" section) - If no section matches, check if a new section is warranted for an entirely new feature
- Read the existing section headings in
Phase 3: Generate updates
Based on the commit prefix and type of change:
feat: — New feature
- Add
- [ ]checklist items to the appropriate section - Each item must be specific, testable, and include the expected result
- Format:
- [ ] [Action to take] → [Expected result] - Add 2-5 items per feature, covering the happy path and key edge cases
- Example:
- [ ] Click "Register" with valid X handle → Token created, redirected to profile page
fix: — Bug fix
- Find the matching
[!]item in the guide that describes the bug - Change
[!]to[!] FIXEDand append the PR/commit reference - Format:
- [!] FIXED (PR #XX) Original bug description → Fix: [brief description of fix] - If no matching
[!]item exists, add a new[x]item describing what was fixed (since it was never tracked as a bug)
refactor: — Refactoring
- Only update if user-visible behavior changed
- If purely internal, report "No bug bash updates needed" and stop
test:, ci:, docs:, chore: — Non-user-facing
- Typically no updates needed. Only update if there's a user-visible side effect.
Phase 4: Verify in browser
This phase applies only to fix: commits that changed items from [!] to [!] FIXED.
- Read the deployment URL from
docs/BUG_BASH_GUIDE.md(look in "Test Environment" or "Prerequisites" section). - If no URL is listed, stop and ask the user for the deployed URL.
- NEVER use localhost. Bug bash verification must happen on a deployed build.
- Open the deployment in the browser using browser automation tools.
- Navigate to the relevant page/feature for the fix.
- Visually confirm the fix works as expected:
- Check that the bug behavior is no longer present
- Check that the correct behavior is now shown
- Take a screenshot as evidence.
If verified successfully:
- Change
[!] FIXEDto[x]with verification notes - Format:
- [x] Original description → Verified: [what was confirmed, date]
If NOT verified:
- Leave as
[!] FIXED— do NOT mark[x] - Report what's still broken and what was observed
- The orchestrator should loop back to fix the issue before re-verifying
If browser verification is not possible (no deployment available, page requires auth that can't be automated, etc.):
- Leave as
[!] FIXED - Note why verification couldn't be completed
- The item will be verified in the next manual bug bash
Guidelines
- Never remove existing checklist items — only add or modify status markers
- Keep checklist items concise but specific enough to be independently testable
- When adding items for a new feature, look at existing items for style/format consistency
- Group related items together under the same section
- If a section doesn't exist for a new feature area, create it following the existing heading hierarchy
- Always include the PR or commit reference when annotating fixes
- Screenshots from browser verification should be saved with descriptive names (e.g.,
history-tab-fix-verified.png)
Verification Rules (MANDATORY)
These rules apply to ALL bug bash verification — both Phase 4 fix verification and general checklist testing.
- DO: Test in the browser — ALL verification must happen via Claude in Chrome MCP tools (navigate, click, screenshot, read page). DO NOT use unit tests,
cast,forge test, contract calls, or code review as verification. If the browser extension is not connected, stop and tell the user. - DO: Test on a deployed build — Read the deployment URL from
docs/BUG_BASH_GUIDE.md. NEVER uselocalhost. Bug bash tests deployed code, not local dev servers. - DO: Act autonomously in the browser — Click buttons, navigate pages, scroll, take screenshots without asking user permission. Browser interactions during testing are routine actions. Only purchases, entering personal data, and account creation need explicit user approval.
- DO: Ask the user to unblock, never skip — When blocked (wallet not connected, insufficient funds, auth required, extension not responding), tell the user exactly what's needed and wait. DO NOT silently skip items or mark them "cannot test" without first asking the user if they can resolve the blocker.
- DO: Follow marking conventions exactly:
[ ]= unverified (not yet tested)[!]= bug found (describe inline)[!] FIXED= fix applied but NOT yet verified in browser[x]= verified working in browser with screenshot evidence- NEVER mark
[x]without having taken a browser screenshot confirming the behavior. Code review or test output is not sufficient.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

