| name | auto-bug-fix |
| description | Use when asked to fix a bug from a JIRA ticket, reproduce a bug on a real mobile device, or run an end-to-end bug-fix cycle (JIRA → reproduce → analyze → test → fix → verify). Also use when user says "fix bug", "reproduce PROJ-1234", or "auto-fix". Requires a connected iOS/Android device with WebDriverAgent running. |
Auto Bug Fix
Autonomous 8-phase workflow: read a JIRA bug ticket, reproduce it on a real device with video evidence, find root cause in source code, write a failing integration test, fix the code, verify on device with vision, and deliver a PR.
When to Use
- User says "fix bug PROJ-1234" or "reproduce PROJ-1234"
- A JIRA ticket ID is provided and the task involves bug reproduction or fixing
- User asks to verify a bug exists on a real device
- User asks for end-to-end automated bug triage
When NOT to use:
- Feature requests (not bugs)
- No JIRA ticket or bug description provided
- No device connected (check with
wda.sh status)
Prerequisites
Verify before starting:
./wda.sh status
which ffmpeg
If WDA is not running, set it up:
WDA_DIR="$HOME/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent"
xcodebuild build-for-testing -project "$WDA_DIR/WebDriverAgent.xcodeproj" \
-scheme WebDriverAgentRunner -destination "id=$(idevice_id -l)" \
-allowProvisioningUpdates DEVELOPMENT_TEAM=<TEAM_ID> CODE_SIGN_IDENTITY="Apple Development"
iproxy 8100 8100 --udid $(idevice_id -l) &
xcodebuild test-without-building -project "$WDA_DIR/WebDriverAgent.xcodeproj" \
-scheme WebDriverAgentRunner -destination "id=$(idevice_id -l)" &
The 8 Phases
digraph workflow {
rankdir=TB;
node [shape=box, style=rounded];
parse [label="1. PARSE\nExtract repro steps from JIRA"];
reproduce [label="2. REPRODUCE\nExecute on device + record"];
evidence [label="3. EVIDENCE\nAttach video to JIRA"];
analyze [label="4. ANALYZE\nFind root cause in source"];
test [label="5. TEST\nWrite failing integration test"];
fix [label="6. FIX\nPatch code, test passes"];
verify [label="7. VERIFY\nRe-run on device, vision confirms"];
deliver [label="8. DELIVER\nCreate PR, update JIRA"];
no_repro [label="Comment on JIRA:\nCould not reproduce", shape=oval];
low_conf [label="Comment on JIRA:\nNeeds human review", shape=oval];
parse -> reproduce;
reproduce -> evidence [label="bug reproduced"];
reproduce -> no_repro [label="3 attempts failed"];
evidence -> analyze;
analyze -> test [label="root cause found"];
analyze -> low_conf [label="confidence too low"];
test -> fix [label="test fails (proves bug)"];
test -> analyze [label="test passes\n(wrong hypothesis)"];
fix -> verify;
verify -> deliver [label="fix confirmed"];
verify -> analyze [label="fix incomplete"];
}
Phase 1: PARSE
Fetch ticket and extract structured reproduction steps.
1. Fetch JIRA ticket (use Atlassian MCP: getJiraIssue)
2. Read: summary, description, comments, attachments, labels
3. Extract:
- App identifier (bundleId / package name)
- Platform (iOS / Android)
- Preconditions (login state, test data)
- Ordered reproduction steps
- Expected vs actual behavior
4. If ticket too vague → comment asking for clarification, STOP
Output: A mental model of the steps. Do NOT generate a YAML file — just understand the steps and execute them directly.
Phase 2: REPRODUCE
Execute steps on device using the hybrid approach (WDA for actions, vision for assertions).
Action execution pattern
SESSION=$(./wda.sh session)
ELEM=$(./wda.sh find "$SESSION" "Login")
RECT=$(./wda.sh rect "$SESSION" "$ELEM")
./wda.sh tap "$SESSION" <x> <y>
sleep 1
./wda.sh screenshot /tmp/step_N.png
Assertion pattern
./wda.sh screenshot /tmp/assert_N.png
Video recording (screenshot stitching)
mkdir -p /tmp/bug_frames
i=0; while true; do
./wda.sh screenshot "/tmp/bug_frames/frame_$(printf '%04d' $i).png"
i=$((i+1)); sleep 0.5
done &
RECORD_PID=$!
kill $RECORD_PID
ffmpeg -framerate 2 -i "/tmp/bug_frames/frame_%04d.png" \
-c:v libx264 -pix_fmt yuv420p /tmp/repro_TICKET.mp4
Key rules
- WDA element find first for taps (instant, exact coordinates)
- Vision fallback only when WDA can't find the element (no accessibility label)
- Never guess coordinates from screenshots — vision is 100-200pt off on iOS
- Retry up to 3 times if bug doesn't reproduce
- If still no repro → comment on JIRA, STOP
Phase 3: EVIDENCE
1. Upload video to JIRA (Atlassian MCP or REST API attachment)
2. Upload bug-state screenshot
3. Add structured comment with per-step pass/fail
4. Transition ticket status if applicable
Phase 4: ANALYZE
1. From bug context, identify likely code areas
- Grep for keywords from the bug (e.g., "cart total", "calculateTotal")
2. Read the relevant source files
3. Trace the code path from UI action to data layer
4. Form root cause hypothesis with specific file:line references
5. Verify by reading more code (cache logic, event handlers, state management)
Confidence check: Must identify specific files and lines. If the root cause is vague ("something in the backend"), flag for human review.
Phase 5: TEST
Write an integration/unit test that exercises the exact buggy code path.
1. Write test that reproduces the bug at the code level (NOT UI level)
2. Run the test → must FAIL (proves the bug exists)
3. If test passes → hypothesis is wrong → go back to Phase 4
Why integration test, not UI test:
- 100x faster (milliseconds vs minutes)
- Deterministic (no device, no VLM, no flakiness)
- Pinpoints exact code under test
- Runs in CI on every commit forever
Phase 6: FIX
1. Apply minimal fix (address root cause, nothing more)
2. Run integration test → must PASS
3. Run full existing test suite → must have no regressions
4. If fix touches >3 files or >50 lines → flag for human review
Phase 7: VERIFY
1. Build the app with the fix (xcodebuild or appropriate build tool)
2. Install on device
3. Re-run exact same steps from Phase 2
4. Record video again
5. Claude vision confirms the previously-failing assertion now PASSES
6. If verification fails → fix is incomplete → back to Phase 4
Phase 8: DELIVER
1. Create git branch: fix/TICKET-ID-short-description
2. Commit fix + new test
3. Create PR via `gh pr create` with:
- Root cause analysis
- Links to reproduction and verification videos
- Test plan (integration test + UI verification)
4. Update JIRA:
- Attach verification video
- Add fix summary comment
- Transition to "In Review"
5. Assign reviewer
Confidence Scoring — When to Stop
| Phase | Stop if... |
|---|
| PARSE | Cannot extract ≥3 concrete steps from ticket |
| REPRODUCE | Bug not reproduced after 3 attempts |
| ANALYZE | Cannot identify specific files/lines (root cause too vague) |
| TEST | Integration test passes (wrong hypothesis) after 2 iterations |
| FIX | Change exceeds 50 lines or 3 files |
| VERIFY | UI verification fails after fix |
When stopped: Comment all findings on JIRA (partial analysis is still valuable), assign to human developer.
Quick Reference: wda.sh Commands
| Command | Usage |
|---|
./wda.sh status | Check WDA is running |
./wda.sh session | Create/get session ID |
./wda.sh screenshot [path] | Capture PNG screenshot |
./wda.sh tap <session> <x> <y> | Tap at coordinates |
./wda.sh type <session> "text" | Type into focused field |
./wda.sh swipe <session> <fx> <fy> <tx> <ty> | Swipe gesture |
./wda.sh find <session> "label" | Find element by label → element ID |
./wda.sh rect <session> <elem> | Get element position → center=(x,y) |
./wda.sh home | Press home button |
Common Mistakes
| Mistake | Fix |
|---|
| Guessing tap coordinates from screenshot | Always use wda.sh find + wda.sh rect first |
| Writing UI test instead of integration test | Integration test is Phase 5; UI test is only Phase 7 verification |
| Large refactoring as "fix" | Minimal fix only — refactoring is a separate ticket |
| Skipping Phase 2 ("I can see the bug in code") | Always reproduce on device — confirms the bug and provides evidence |
| Not recording video | Video is the evidence that makes the PR reviewable |
