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:

# 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:

## 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