agentleFS
cryptofish7cryptofish7/claude-skills/skills/bug-bash-update/SKILL.md

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".

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
  1. Distinctive:

    Read the changed files to understand the scope of the change.

    line 20
  2. Distinctive:

    If no meaningful changes are detected (e.g., only CI, docs, or config changes with no user-visible impact), report "No bug bash updates …

    line 24
  3. Very specific:

    Read docs/BUG_BASH_GUIDE.md in full.

    line 28
  4. Very specific:

    Read the existing section headings in docs/BUG_BASH_GUIDE.md

    line 30
  5. Very specific:

    Use directory structure and component names as signals (e.g., components/auth/ → an "Authentication" section)

    line 32
  6. Distinctive:

    If no section matches, check if a new section is warranted for an entirely new feature

    line 33
  7. Very specific:

    Add - [ ] checklist items to the appropriate section

    line 40
  8. Distinctive:

    Add 2-5 items per feature, covering the happy path and key edge cases

    line 43
  9. Very specific:

    If no matching [!] item exists, add a new [x] item describing what was fixed (since it was never tracked as a bug)

    line 50
  10. Distinctive:

    Only update if user-visible behavior changed

    line 53
  11. Distinctive:

    If purely internal, report "No bug bash updates needed" and stop

    line 54
  12. Very specific:

    Read the deployment URL from docs/BUG_BASH_GUIDE.md (look in "Test Environment" or "Prerequisites" section).

    line 63
  13. Distinctive:

    If no URL is listed, stop and ask the user for the deployed URL.

    line 64
  14. Distinctive:

    NEVER use localhost. Bug bash verification must happen on a deployed build.

    line 65
  15. Distinctive:

    Check that the bug behavior is no longer present

    line 69
  16. Distinctive:

    Check that the correct behavior is now shown

    line 70
  17. Very specific:

    Leave as [!] FIXED — do NOT mark [x]

    line 78
  18. Distinctive:

    Never remove existing checklist items — only add or modify status markers

    line 89
  19. Distinctive:

    Keep checklist items concise but specific enough to be independently testable

    line 90
  20. Distinctive:

    When adding items for a new feature, look at existing items for style/format consistency

    line 91
  21. Distinctive:

    If a section doesn't exist for a new feature area, create it following the existing heading hierarchy

    line 93
  22. Distinctive:

    Always include the PR or commit reference when annotating fixes

    line 94
  23. Very specific:

    NEVER mark [x] without having taken a browser screenshot confirming the behavior.

    line 114

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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)
  2. Read the changed files to understand the scope of the change.
  3. Note the commit prefix (feat:, fix:, refactor:, docs:, chore:, test:, ci:).
  4. 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

  1. Read docs/BUG_BASH_GUIDE.md in full.
  2. 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

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 [!] FIXED and 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.

  1. Read the deployment URL from docs/BUG_BASH_GUIDE.md (look in "Test Environment" or "Prerequisites" section).
  2. If no URL is listed, stop and ask the user for the deployed URL.
  3. NEVER use localhost. Bug bash verification must happen on a deployed build.
  4. Open the deployment in the browser using browser automation tools.
  5. Navigate to the relevant page/feature for the fix.
  6. Visually confirm the fix works as expected:
    • Check that the bug behavior is no longer present
    • Check that the correct behavior is now shown
  7. Take a screenshot as evidence.

If verified successfully:

  • Change [!] FIXED to [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.

  1. 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.
  2. DO: Test on a deployed build — Read the deployment URL from docs/BUG_BASH_GUIDE.md. NEVER use localhost. Bug bash tests deployed code, not local dev servers.
  3. 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.
  4. 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.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.