> ## Documentation Index
> Fetch the complete documentation index at: https://personal-ce79cb71.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue Lifecycle: From Detection to Resolution in BugViper

> Track how BugViper issues move from open to resolved to fixed. Understand nitpick, valid, and outside_diff classifications and automatic resolve detection.

Every finding that BugViper surfaces goes through a structured lifecycle — from initial detection, through developer acknowledgment, to confirmed resolution. This gives you and your team a reliable audit trail of what was caught, what was addressed, and what was actually fixed in code. Understanding the lifecycle helps you get the most out of BugViper's tracking and analytics features.

## Issue Classification

Before any finding becomes an issue, it passes through the **verifier pass** — a dedicated step that validates each finding against the actual PR diff. The verifier assigns one of three labels to every finding:

<Note>
  The verifier label determines whether a finding is posted as an inline comment. Only `valid` issues appear as inline comments on your PR. The others are recorded internally and included in the summary, but don't create comment noise on lines you aren't actively working on.

  | Label          | What it means                                                             | Posted inline? |
  | -------------- | ------------------------------------------------------------------------- | -------------- |
  | `valid`        | Confirmed issue within the changed lines of the PR diff — high confidence | ✅ Yes          |
  | `nitpick`      | Minor style or low-confidence suggestion — not worth blocking the PR      | ❌ No           |
  | `outside_diff` | Real concern, but in code outside the lines changed by this PR            | ❌ No           |
</Note>

**`valid`** issues are the ones that matter most. The agent identified a problem, and the verifier confirmed it sits within code you actually changed in this PR. These are posted as inline comments at the relevant line.

**`nitpick`** issues are surfaced in the review summary but don't create inline noise. They might be valid style suggestions or low-confidence observations that aren't worth blocking a merge over.

**`outside_diff`** issues are findings in parts of the codebase that your PR doesn't touch. The code may have a real problem, but since you didn't change it in this PR, BugViper records it without posting an inline comment. These may surface as `valid` issues in a future PR that does touch those lines.

## Issue States

Once a `valid` issue is created, it moves through three states:

<Steps>
  <Step title="Open">
    A newly detected issue starts in the **Open** state. BugViper has posted an inline comment on the relevant line in your PR, and the issue is recorded with a link back to that GitHub comment thread.

    Open issues appear in your repository's issue list in the BugViper dashboard, and count toward your repo's open issue total.
  </Step>

  <Step title="Resolved">
    An issue moves to **Resolved** when the GitHub comment thread associated with it is marked as resolved on GitHub — either by the PR author or a reviewer.

    This state means the team has acknowledged the finding. The code change may or may not have been applied yet — BugViper doesn't assume resolution means the bug is fixed, only that someone has seen it and acted on the thread.
  </Step>

  <Step title="Fixed">
    An issue is marked **Fixed** when BugViper reviews a subsequent PR and confirms that the underlying code problem is no longer present.

    This is **automatic resolve detection** — BugViper doesn't rely on you to manually close issues. When a later review run covers the same file and function, BugViper checks whether the previously reported issue still exists in the code. If it doesn't, the issue is automatically transitioned to Fixed and marked with a checkmark in the dashboard.
  </Step>
</Steps>

## Automatic Resolve Detection

When BugViper runs on a new PR, it doesn't only look for new issues — it also checks your repository's open issue list against the current state of the code. If a previously reported `valid` issue has been addressed in the code (even if it was fixed in a different PR than the one that introduced it), BugViper automatically marks it as `fixed`.

This means your issue tracker stays accurate without any manual housekeeping. Issues that were silently fixed during a refactor will be reflected correctly in your dashboard and analytics.

<Tip>
  To manually resolve all of BugViper's inline comments on a PR at once — for example, after you've addressed every finding in a batch of commits — comment `@bugviper resolve` on the PR. This marks the open threads as resolved without requiring you to click through each inline comment individually on GitHub.
</Tip>