auto-bug-fix

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:

# 1. WDA running on device
./wda.sh status
# Expected: WDA ready=True device=iphone iOS=...

# 2. JIRA accessible (Atlassian MCP)
# Use mcp__claude_ai_Atlassian__getJiraIssue

# 3. Source code accessible
# Current working directory has the project source

# 4. ffmpeg for video stitching (optional)
which ffmpeg

If WDA is not running, set it up:

# Build WDA
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"

# Port forward + launch
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

# For each action step:

# 1. Find element by label (fast, exact)
SESSION=$(./wda.sh session)
ELEM=$(./wda.sh find "$SESSION" "Login")
RECT=$(./wda.sh rect "$SESSION" "$ELEM")
# Parse center coordinates from rect output

# 2. Tap at exact coordinates
./wda.sh tap "$SESSION" <x> <y>

# 3. Wait for UI to settle
sleep 1

# 4. Screenshot for evidence
./wda.sh screenshot /tmp/step_N.png
# Read the screenshot to verify action succeeded

Assertion pattern

# Screenshot → Read with Claude vision → evaluate
./wda.sh screenshot /tmp/assert_N.png
# Then use Read tool on the PNG
# Claude vision evaluates: "Is the cart total showing $29.99?"

Video recording (screenshot stitching)

# Start capturing frames in background during test
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=$!

# ... run test steps ...

# Stop recording and stitch
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