# Bug Analyzer

> Analyze a confirmed failing scenario, separate observation from inference, classify defect confidence, and produce durable bug evidence. Use after qa-agent routes bug analysis.

- Skill: `neplich/bug-analyzer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neplich/bug-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neplich/bug-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Neplich (https://skillmd.com/u/neplich)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neplich/bug-analyzer

---


# Bug Analyzer

Turn a failing scenario into a defect artifact only when the evidence crosses a useful threshold. This skill is about judging defect quality, not filling a template.

The durable evidence inventory explicitly records presence or absence for the
observed error message, stack trace, screenshot, console output, network
evidence, trace, environment, and reproduction result. Missing evidence stays
`missing` or `unavailable`; never omit the field or infer it existed.

## Reader-Facing Writing Composition

For substantial reader-facing prose, co-load `human-writing` even on direct
invocation; use the same context, not a later pass. This Skill retains evidence,
facts, required structure, paths, gates, and verification. Skip code-, config-, schema-,
lockfile-, and data-only output.

## Shared QA Directory Contract

For feature-scoped E2E or reusable regression artifacts, prefer the function
tree directory when it exists:

`docs/qa/e2e/{feature_path}/`

- `cases/` stores reusable cases; every E2E case must be one Markdown file
  named `TC-NNN-<short-slug>.md`.
- `scripts/` stores matching repeatable flow snippets when the reproduction
  should become executable.
- `FLOW_INDEX.md` records flow, source, route, or API evidence used to derive
  reusable coverage.
- `results/` and `_reports/` store versioned execution evidence and summaries.

Bug analysis does not create broad test plans, but when a confirmed E2E
reproduction should become reusable regression coverage, write or update one
case file under `docs/qa/e2e/{feature_path}/cases/` and reference
it from the defect artifact.

If the reusable TC would validate an existing-feature change or bug fix as an
acceptance expectation, require PRD/TRD expectation alignment and a confirmed
`docs/engineer/{feature_path}/IMPLEMENTATION_PLAN.md` before creating or
updating that TC. Read `docs/pm/{feature_path}/PRD.md` and
`docs/engineer/{feature_path}/TRD.md` from the same path. If the feature path
or expectation is unclear, keep the defect artifact focused on the observed
failure and mark reusable E2E coverage as `blocked`.

Gate strength for that reusable TC follows the `change_tier` contract in
`AGENTS.md` (变更分级契约). Consume `change_tier` from the handoff when
present, or self-assess it per that contract. For `hotfix` with unchanged
approved PRD/TRD expectations, only require covering the direct impact paths
and appending results, and accept the confirmed lightweight plan form for the
plan gate; for `standard` and above, keep the full PRD/TRD expectation
alignment gate. Tiering never waives evidence, and a request that changes
approved PRD/TRD expectations is never `hotfix` — route it back to PM.

## When to Use

- A test, manual check, or exploratory pass fails and needs triage
- A user reports broken behavior and the report needs validation
- QA needs a defect record that can survive handoff to engineering or release review

## Core Principle

Do not treat every failure as a confirmed bug. First collect evidence, then classify the report, then choose the output path that fits the repo context.

## Mandatory Defect Record

Every completed analysis must create a durable Markdown artifact unless the
user explicitly requested a different repository-native tracker. Record these
as separate fields: evidence status, confidence, severity with rationale,
potential user/system impact, implementation or release impact, and evidence
references. Thin evidence remains `suspected / needs more evidence`; request
the decisive product/app version, environment, reproduction, expected/actual,
logs/network/trace, and screenshots needed to change that status.

When no E2E function tree applies, write the dated-free report under
`docs/qa/{feature_path}/bug-<short-slug>.md`, never `docs/qa-reports/`. A
confirmed reusable E2E reproduction instead uses the function-tree case,
script, versioned result, and report paths from the shared QA contract.

## PM Handoff Entry Gate

Before analyzing a failure, require a PM/QA handoff packet, existing QA evidence,
or another confirmed failure source that defines the intake scope. If the user
directly invokes this specialist with a raw bug report and no route context,
return the request to `pm-agent` for classification unless the prompt supplies
enough evidence to remain a QA-only defect intake.

Use the PM-side packet definition in
the plugin-local generated `../qa-agent/_internal/_generated/shared-contracts/handoff-contract.md`.

## Step 1 — Intake evidence

宿主存在 `docs/site/standards/change-map.yaml` 时，项目探索先按 pm-agent 维护的 `consumption-contract.md`（the plugin-local generated `../qa-agent/_internal/_generated/shared-contracts/consumption-contract.md`）执行“任务落点 → change-map 反查 → 精准读取 → 关键判断回代码验证”；不存在时静默沿用当前代码探索。

Collect the minimum evidence needed to judge the report:

- Failing scenario or symptom
- Source evidence from QA notes, user report, logs, screenshots, traces, console output, network output, or test output
- Environment and build context such as branch, commit, build number, release channel, feature flag state, browser or device, and runtime version

If evidence is missing, ask for it or record the gap explicitly. Do not guess.

## Step 2 — Classify the report

Classify the intake using evidence-confidence vocabulary:

- `confirmed and reproducible` - the failure is observed more than once or is deterministically replayable
- `confirmed but environment-sensitive` - the defect is real, but depends on environment, build, data, timing, permissions, feature flags, or state
- `suspected / needs more evidence` - the report is plausible but not yet strong enough to confirm

Keep the axes separate: evidence status describes reproducibility or sensitivity, while confidence describes how complete and strong the supporting proof is. A report can be `confirmed and reproducible` with medium confidence if the evidence is partial, or `suspected / needs more evidence` with low confidence if the proof is thin; do not collapse the two into one label.

Use the classification to decide whether the artifact should read like a defect report, a scoped investigation note, or an evidence request.

## Step 3 — Assess severity and confidence

Separate impact from certainty.

- Severity describes user or system impact
- Confidence describes how strongly the evidence supports the defect claim

Severity should include a rationale, not just a label. A low-confidence report can still be high severity if the potential impact is serious.

## Step 4 — Build the defect artifact

The defect artifact must include:

- Title
- Severity with rationale
- Reproduction steps
- Expected behavior
- Actual behavior
- Evidence attachments or references
- Confidence statement
- Implementation impact or release impact

Keep reproduction steps grounded in the observed evidence. If the failure is not fully reproducible, say what part is deterministic and what part is not.

## Step 5 — Choose the output path

Pick the durable output that matches the repo workflow and the user request.

- Use a local Markdown artifact when the work is being tracked in-repo, when the repo does not require GitHub workflow, or when the user asked for a file-based handoff
- For E2E-related defects, prefer the function-tree report path:
  `docs/qa/e2e/{feature_path}/_reports/{platform-version}/test-reports-{test-time}.md`
- For non-E2E defects where the repo has no stronger convention, use
  `docs/qa/{feature_path}/bug-<short-slug>.md`
- Use a GitHub issue only when the repository workflow explicitly wants issue tracking or the user requested an issue

Do not assume GitHub issue creation is the primary output. Do not mutate code, commit changes, or invent a delivery workflow as part of this skill.

## Step 6 — Write the report

### Local Markdown artifact

Write the defect report to the repo's documented QA or bug-tracking location. If the repo already has a bug or QA report directory, use that convention. If not, use a clear Markdown file path agreed with the repo context.

Suggested content structure:

```markdown
# Defect: [short title]

## Classification
- Evidence status: confirmed and reproducible / confirmed but environment-sensitive / suspected / needs more evidence
- Severity: [severity] - [rationale]
- Confidence: [high / medium / low] with a short explanation

## Scenario
[failing scenario or symptom]

## Environment and Build Context
- Branch:
- Commit:
- Build / release:
- Platform:
- Browser / device / runtime:
- Flags / data / permissions:

## Reproduction Steps
1. ...
2. ...
3. ...

## Expected
[expected behavior]

## Actual
[actual behavior]

## Evidence
- [log / screenshot / trace / test output reference]
- [link or file path]

## Impact
[implementation or release impact]
```

If the report adds a reusable E2E regression case, include:

```markdown
## Reusable Test Case
- Test case file: docs/qa/e2e/{feature_path}/cases/TC-NNN-<short-slug>.md
- Purpose: [why this case should be rerun]
```

### GitHub issue

Create an issue only when the repo workflow or user request calls for issue tracking. The issue body should preserve the same defect contract as the Markdown artifact and should link back to supporting evidence where possible.

## Step 7 — Handle weak evidence

If the report is `suspected / needs more evidence`, keep the artifact honest:

- State what is missing
- Mark the current confidence level clearly
- List the next evidence needed to confirm or rule out the defect
- Avoid overstating reproducibility

## Step 8 — Final check

Before returning the artifact, verify that the report answers these questions:

- What failed?
- How strong is the evidence?
- How severe is the impact?
- What proof supports the claim?
- Where should the durable record live?

## Configuration

- Evidence first, template second
- Confidence language must be explicit
- Default output is a Markdown artifact unless the repository workflow or user request requires GitHub issue tracking

## Edge Cases

- **No reproducible failure yet**: classify as `suspected / needs more evidence`
- **Environment-specific failure**: keep the defect confirmed, but note the sensitivity in the classification and impact
- **Multiple symptoms from one root cause**: document the primary failure and list secondary symptoms as supporting evidence
- **Evidence conflicts**: prefer direct runtime evidence over summaries, and record the conflict rather than hiding it