Docs / Bug Fix Workflow

Bug Fix Workflow

The most powerful feature of ContextQA MCP. Automate the entire cycle from bug report to verified fix — reproduce, investigate, fix, and verify — all through your AI assistant.

How It Works

The bug fix workflow orchestrates four stages. Your AI assistant handles the tool calls — you just have a conversation.

1
Reproduce

Creates a targeted reproduction test case from your bug ticket. Executes it to confirm the bug actually exists. Returns investigation results with fix suggestions and relevant code pointers.

2
Investigate

Aggregates telemetry data — network logs, console errors, DOM snapshots, and traces. Performs root cause analysis and optionally queries your repo to locate the responsible code.

3
Fix & Deploy

You apply the fix (the AI gives you guidance) and deploy to your test environment. This is the only manual step — the rest is automated.

4
Verify

Re-runs the reproduction test against your live environment. If it passes, the fix worked. If it fails, iterate back to step 3. Once verified, generate a structured fix report for your ticket.

Step-by-Step Guide

Step 1: Start the Bug Fix

Paste the bug ticket details into your AI assistant. Include as much context as possible — the URL, steps to reproduce, and optionally your repo URL.

Prompt 
Fix this bug:

Title: Checkout fails when applying discount code
Description: Users report that entering a valid discount code
on the checkout page returns "Invalid code" error.
URL: https://staging.myapp.com/checkout
Steps to reproduce:
1. Add any item to cart
2. Go to checkout
3. Enter code SAVE20
4. Click Apply

Our repo is at https://github.com/myorg/myapp

What happens behind the scenes:

  • A reproduction test case is created from the ticket details
  • The test is executed against the live URL
  • Investigation results are returned with root cause analysis
  • If a repo URL is provided, relevant code files are identified
  • Fix suggestions are generated based on the findings

Step 2: Review the Investigation

The AI will return a detailed investigation including:

  • Confirmation that the bug was reproduced (test failed as expected)
  • Network log analysis (failed API calls, error responses)
  • Console error summary
  • Fix suggestions with code pointers
  • A link to watch the test execution recording

You can ask follow-up questions:

Follow-up prompts 
Show me the full network logs for the failed request.

What console errors appeared during the test?

Get me the trace URL so I can watch the recording.

Step 3: Apply the Fix

Based on the investigation, fix the code and deploy to your test environment. This is the only part you do manually.

Make sure your fix is deployed before moving to verification. The test runs against the live URL — not your local code.

Step 4: Verify the Fix

Once deployed, ask the AI to re-run the reproduction test:

Prompt 
I've deployed the fix. Verify if the bug is fixed.

The verification will re-execute the same test case against the current live state:

PASSED — The fix worked! Proceed to report.
FAILED — Fix didn't work. Go back to step 3.

Step 5: Report to Ticket

After a successful verification, generate a structured fix report. The ContextQA tool returns the report body; your assistant posts it through a separate Linear/Jira connector call when authorized:

Prompt 
Post the fix report to the ticket. The fix was: [brief description of what you changed]

The report includes: resolution status, verification results, elapsed time, execution URL, and a recommendation to close the ticket.

Example Conversation

Here's what a complete bug fix session looks like:

You
Fix this bug:

Title: Login page shows "undefined" error after submitting valid credentials
URL: https://staging.myapp.com/login
Steps: Enter valid email/password, click Sign In
Repo: https://github.com/myorg/myapp
AI
I've created reproduction test case #247 and executed it. The bug is confirmed — the test failed as expected.

Root cause: The login API returns { token: "..." } but the frontend expects { access_token: "..." }. The response mapping in src/auth/login.ts:42 tries to access res.access_token which is undefined.

Suggested fix: Update the response mapping to use res.token instead of res.access_token, or update the API to return access_token.

You can watch the test execution here: [trace URL]
You
I've fixed the mapping and deployed. Verify if it works now.
AI
Verification complete. Test case #247 PASSED. The login flow now works correctly — user is redirected to the dashboard after sign-in.

Ready to post the fix report to the ticket?
You
Yes, post the report.
AI
Fix report generated. Here's the summary posted to the ticket:

Status: FIXED | Verified: PASSED | Time: 12 minutes
Resolution: Updated response mapping in login.ts to use correct token field name.

Important Rules

FAILED = fix didn't work. The test runs against the live deployed URL. If verification fails, it means the bug is still present — not a timing or deployment issue. Go back and fix it.
Can't report FIXED without PASSED. The system enforces this — you cannot generate a "FIXED" report unless the verification test actually passed.
Each verification is a fresh execution. Every time you call verify, it re-runs the test against the current live state. No caching, no shortcuts.
Include the repo URL for better results. When you provide the repo, the AI can pinpoint the exact file and line causing the issue.

What to Include in Your Bug Report

The more context you provide, the faster and more accurate the fix will be.

Field Required Why It Matters
Bug description Required The AI uses this to understand what's broken
URL Required The test needs a target to run against
Steps to reproduce Recommended Improves reproduction accuracy significantly
Repo URL Optional Enables code-level investigation and specific fix suggestions
Knowledge base ID Optional Applies custom test rules (e.g., accessibility checks)
Deployment info Optional Helps the AI understand your deployment pipeline