bug-bash

The user wants to work through a bug using the bug-bash workflow.

Overview

Work through bugs in BUGS.md one at a time. Each bug gets:

• A GitHub issue for tracking
• A dedicated branch off main
• A diagnosis posted to the issue before any code is written
• Related bugs with the same root cause identified and bundled in
• A fix developed iteratively with the user
• A Playwright smoke test in tests/playwright/
• A clean lint + build
• A PR linked to the issue

Step-by-step workflow

1. Compress and start clean

Run /compact to compress the conversation context before starting.

Then:

git checkout main && git pull && npm install

If there are unstaged changes on main that are just formatting (Prettier), commit them before branching:

git add <files> && git commit -m "style: prettier formatting from remote main"

2. Pick the next bug

First, detect who is running the session:

gh api user --jq '.login'

Login	Person	Bug preference
zenkat	Brian	Backend / DB bugs first
BeFriendDev	Janine	UX / frontend bugs first

Classifying bugs:

• UX / frontend — items under any "UX / Copy" subsection; visual issues; navigation issues; copy/text fixes; component bugs that don't require schema or migration changes
• Backend / DB — Pre-Launch Blockers section; anything mentioning migrations, RLS, Edge Functions, schema columns, FK constraints, or DB-layer changes

Selection rules:

• If the user specifies a bug, use that — no preference filtering applies.

• If no bug is specified, scan BUGS.md for open items (not marked [FIXED IN PRxx] or [CANNOT REPRODUCE #N]) and apply the caller's preference: surface the first bug matching their preferred type. If none of the preferred type remain, fall through to the other type.

• Exception — Janine with only backend bugs remaining: if the caller is BeFriendDev and every remaining open bug is backend / DB, show this warning before proceeding:

  ⚠️ The remaining open bugs are all backend / DB changes — Brian should probably take these. Want to pick one anyway? (yes / skip)

  If she says skip, close out with "Nothing left for Janine to take right now." If she says yes, proceed with the first available bug regardless of type.

3. Check for in-flight work

Use the Agent tool with model: "haiku" to run the following and return whether any open issue or PR already covers this bug:

gh issue list --state open
gh pr list --state open

If an open issue or PR already covers this bug, skip it and pick the next one. The issue is the canonical "claimed" signal — it exists before a branch is made, so checking issues catches the full window. This prevents two people from picking up the same bug when BUGS.md on main hasn't been updated yet (because the fix is still in a feature branch).

4. Create a GitHub issue

Always write the body to a temp file and pass it with --body-file — never use --body "..." for multi-line content. Backticks and special characters in inline --body strings are interpreted by the shell, corrupting the output.

cat > /tmp/gh_body.md << 'EOF'
...body content...
EOF
gh issue create --title "..." --body-file /tmp/gh_body.md

Body should include: Description, Expected behavior, Actual behavior, Steps to reproduce. The last line of the body must be the original verbatim text from BUGS.md, labeled:

**Original report:** <exact text from BUGS.md>

Note the issue number — you'll use it throughout.

5. Create a branch

Before branching, check whether any open PRs touch the same files you are about to modify:

gh pr list --state open

If another open PR modifies the same file(s), stop and wait for it to merge before creating this branch. Never borrow file content from an unmerged branch — always let it land on main first, then pull.

git checkout main && git pull
git checkout -b fix/<short-description>

The git pull must happen immediately before git checkout -b — not earlier in the session. Open PRs can merge at any time and stale local main is the #1 cause of merge conflicts.

Branch naming: fix/ prefix, lowercase, hyphen-separated. Example: fix/onboarding-cache-clear.

6. Diagnose before coding

Read the relevant source files first. Check git history to see if the bug was already fixed:

git log --oneline --all --grep="<keyword>" -i
git show <commit> --stat

If it was already fixed, verify with a smoke test, then close the issue and move on.

If it needs a fix, understand the root cause fully before writing any code.

7. Post diagnosis to GitHub issue

Before writing any code, post your diagnosis as a comment on the issue. Write the body to a temp file:

cat > /tmp/gh_body.md << 'EOF'
## Diagnosis

...diagnosis content...
EOF
gh issue comment <N> --body-file /tmp/gh_body.md

Include: root cause, affected file(s) and line numbers, proposed fix approach.

8. Check BUGS.md for related issues

Use the Agent tool with model: "haiku" to scan the remaining open items in BUGS.md and return any that share the same root cause as the bug you just diagnosed. If any do:

• Update the GitHub issue title and body to reflect the broader scope
• List the related bugs explicitly in the issue
• Fix them all in this branch

cat > /tmp/gh_body.md << 'EOF'
...updated body...
EOF
gh issue edit <N> --title "..." --body-file /tmp/gh_body.md

This way all related bugs are tracked together and fixed atomically rather than discovered after the fact.

9. Fix the bug(s)

Make the minimum change needed. Follow all CLAUDE.md conventions:

• No as any, no @ts-ignore
• Types go in src/types/index.ts
• Mock data must match types
• No speculative abstractions

Iterate with the user as needed.

10. Write a Playwright smoke test

All tests go in tests/playwright/ — never in /tmp or anywhere else.

Each test file should:

• Have a descriptive name (test_<what_it_tests>.py)
• Include a docstring with description, usage, and install instructions
• Use python3 -m playwright install chromium (not the bare playwright command)
• Be self-contained and runnable independently — spin up its own Vite dev server on a unique port rather than assuming one is already running
• Start the server with VITE_USE_MOCK=true and --strictPort — without --strictPort, Vite silently moves to the next port when the target is occupied, causing the test to hit a stale server and fail with misleading results
• Pick a port not used by any other test (check grep -r "^PORT" tests/playwright/ to see what's taken)
• Follow the pattern in test_inapp_banner.py: subprocess.Popen, wait_for_server(), try/finally to terminate

After writing the test, add a row to the test table in docs/DEVELOPER_BRIEF.md:

| `test_<name>.py` | What it covers |

11. Confirm the fix

Run the smoke test:

python3 tests/playwright/<test_file>.py

All checks must pass before proceeding.

12. Lint, build, and test

All must be clean before committing:

npm run format && npm run build && npm test

The chunk size warning is expected — ignore it.

If the PR adds files in scripts/ (CLI scripts not covered by tsconfig.app.json), type-check them separately:

npx tsc --noEmit --target ES2020 --module ESNext --moduleResolution bundler --skipLibCheck --strict scripts/<file>.ts

Also run the full Playwright suite to check for regressions:

bash scripts/run-playwright-tests.sh

This runs all tests in parallel — do not use a for loop.

Any test that was passing on main must still pass. If a test is now failing that wasn't before, investigate and fix before committing. If tests were already failing on main before you started, confirm this explicitly by checking out main, running those specific tests, and verifying the same failures reproduce — then document them as pre-existing in your commit message or PR body.

13. Commit

git add <specific files>
git commit -m "fix: <description>\n\nCloses #<N>\n\nCo-Authored-By: ..."

Use conventional commit format: fix:, feat:, docs:, refactor:, style:. Always include Closes #<issue-number> in the commit body.

14. Update BUGS.md

Mark the fixed item(s) inline — do not move them to a separate section:

- [FIXED IN PR#<N>] ~~original bug description~~

The [FIXED IN PR#N] tag is NOT struck through — only the description is.

Commit this change:

git add BUGS.md && git commit -m "docs: mark bug(s) fixed in PR#<M>"

15. Push and file PR

git push -u origin fix/<branch-name>

cat > /tmp/gh_body.md << 'EOF'
...PR body...
EOF
gh pr create --title "fix: ..." --body-file /tmp/gh_body.md

PR body template:

## Summary

- <bullet 1>
- <bullet 2>

Closes #<N>

## Test plan

- [ ] `npm test` passes (Vitest unit tests)
- [ ] `bash scripts/run-playwright-tests.sh` passes (all Playwright smoke tests)
- [ ] <manual check if needed>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Key conventions

• Never write code before posting a diagnosis to the issue
• Always check git history before assuming the bug is unfixed
• Scan for related bugs right after diagnosis — bundle them into the same issue and branch
• Tests always go in tests/playwright/ — never /tmp or anywhere else
• BUGS.md uses inline strikethrough — [FIXED IN PR#N] ~~description~~ — not a separate Fixed section
• Branch off main — never off another feature branch, and always git pull immediately before git checkout -b, not earlier in the session
• Check open PRs before branching — gh pr list --state open; if another open PR touches the same files, wait for it to merge first. Never copy file content from an unmerged branch.
• One branch per bug (or per tightly related cluster of bugs with the same root cause)
• The bugfix-workflow branch is a meta-branch for developing this skill — it is not a bug fix branch
• Push only when creating a PR — commit locally otherwise
• Playwright install: python3 -m playwright install chromium (the bare playwright command may not be on PATH)

Keeping changes on the right branch

Every change must live on the branch whose bug caused it. This is easy to violate when multiple branches are open at once.

Rule: If fixing bug A requires updating shared files (types, mock data, tests), those changes go on bug A's branch — not on whichever branch happens to be checked out.

Before committing, ask: Does every file in this diff belong to this bug? If a change was necessitated by a different bug's root cause, move it:

1. Add it to the correct branch:

   git checkout fix/<correct-branch>
   # make the change, commit
   

2. Remove it from the wrong branch:

   git checkout fix/<wrong-branch>
   git revert <commit-hash> --no-edit
   git push
   

Common mistake: Discovering that mock data or types are wrong while working on bug B, fixing them on bug B's branch — but the real cause is bug A. The fix belongs in bug A's PR so reviewers see the full, coherent change.

After reverting: verify with git diff main...<branch> --stat that the branch only touches files relevant to its bug.

Project-specific notes (BeFriend app)

• Dev server: npm run dev at http://localhost:5173
• Mock mode: VITE_USE_MOCK=true in .env (currently false — real Supabase)
• Tests allowed without prompting: python3 tests/playwright/* (set in .claude/settings.json)
• Playwright test table lives in docs/DEVELOPER_BRIEF.md under "UI Smoke Tests (Playwright)"
• BUGS.md is in the project root