> ## Documentation Index
> Fetch the complete documentation index at: https://www.bugzy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Triage test failures

> Bugzy classifies every test failure as a product bug, test issue, environment issue, or test adjustment — auto-fixes test problems, files real bugs, filters out environment noise, adapts to app changes, and learns from team feedback.

Defect management and test maintenance — instead of dumping raw test failures on your team, Bugzy triages every failure, classifying it as a product bug, test issue, environment issue, or test adjustment. Test issues are fixed automatically. Product bugs are filed in your issue tracker with reproduction steps. Environment issues are logged internally but not reported to the customer. Test adjustments detect when your app intentionally changed and automatically update tests to match — a positive signal that Bugzy adapts to your development pace. Over time, Bugzy learns from team feedback to improve triage accuracy.

## Triage classification

| Classification    | Meaning                                                                                                                                                                      | Action taken                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Product bug       | Real defect in the application                                                                                                                                               | Filed in issue tracker with reproduction steps                    |
| Test issue        | Problem with test code (stale selector, timing race, outdated assertion)                                                                                                     | Auto-fixed by test-engineer subagent                              |
| Environment issue | Both test and product code are correct, but the environment doesn't support the functionality (broken signed URLs, headless browser limitations, missing third-party config) | Logged internally, NOT reported to customer                       |
| Test adjustment   | Application intentionally changed (button renamed, page redesigned, workflow updated) and the test needs to adapt                                                            | Auto-fixed by test-engineer subagent, team notified of app change |

Some failure symptoms overlap between categories. For example, a timeout waiting for an element can be a test issue (flaky wait) or a product bug (the UI never rendered the expected element). Bugzy uses contextual signals -- did the preceding action succeed? Is the element present but misplaced? -- to resolve ambiguity and classify based on root cause, not on whether the test can be patched.

Classification uses the project's knowledge base and previous triage history. Accuracy improves over time.

## Auto-fix behavior

When the test-engineer subagent fixes a test issue:

<Steps>
  <Step title="Analyze error">
    Analyzes the error message and stack trace.
  </Step>

  <Step title="Identify root cause">
    Identifies the root cause — selector change, timing issue, or assertion drift.
  </Step>

  <Step title="Apply fix">
    Modifies the test file with the fix.
  </Step>

  <Step title="Validate">
    Re-runs the test to validate the fix works.
  </Step>

  <Step title="Commit">
    If the fix works, commits it to the repo.
  </Step>

  <Step title="Retry if needed">
    If the fix fails, retries with a different approach (up to 3 total attempts).
  </Step>
</Steps>

Fixed tests are committed as part of execution — the repo always has the latest working test code.

## Bug filing

For product bugs, Bugzy creates issues in your connected tracker (Jira, Azure DevOps, Asana, Linear). Each issue includes:

* Failure description and steps to reproduce
* Screenshots from the failure point
* Browser and environment details
* Link to test file and execution logs

Bugzy checks existing issues before creating new ones to avoid duplicates.

## Disputed findings

When a team member disagrees with Bugzy's classification:

<Steps>
  <Step title="Reply to Bugzy">
    Reply to the finding message in Slack or Teams.
  </Step>

  <Step title="Process reply">
    The `handle-message` task processes the reply.
  </Step>

  <Step title="Evaluate dispute">
    Bugzy evaluates the dispute against test evidence.
  </Step>

  <Step title="Update finding">
    If the dispute is valid, the finding is updated and the knowledge base is adjusted.
  </Step>

  <Step title="Confirm resolution">
    Bugzy confirms the resolution in the thread.
  </Step>
</Steps>

Disputes are recorded in `disputed-findings.md` and directly adjust future triage behavior.

## How accuracy improves

| Dimension       | Mechanism                          | Impact                                    |
| --------------- | ---------------------------------- | ----------------------------------------- |
| Triage accuracy | Knowledge base + disputed findings | Fewer false positives, fewer missed bugs  |
| Test stability  | Auto-fix + selector learning       | Fewer flaky tests, less maintenance       |
| Test coverage   | Event processing + change analysis | Tests target areas most likely to break   |
| Team efficiency | Feedback loop + message handling   | Less noise, more actionable notifications |

After several execution cycles, Bugzy typically reaches a steady state where most test issues are auto-fixed, product bugs are accurately classified, and notifications contain only actionable information.