Back to Details

qe-bug-reporting-excellence

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Reporting Excellence

优质Bug报告撰写指南

<default_to_action> When reporting bugs:
  1. TITLE: 
    [Component] fails [Condition] causing [Impact]
  2. DESCRIBE: Expected behavior → Actual behavior → Steps to reproduce
  3. INCLUDE: Environment, severity, screenshots/logs, business impact
  4. ISOLATE: Narrow down conditions (browser, user, amount thresholds)
  5. ONE BUG = ONE REPORT (don't combine issues)
Bug Report Formula:
markdown
undefined
<default_to_action> 提交Bug时请遵循以下步骤：
  1. 标题：
    [Component] fails [Condition] causing [Impact]
  2. 描述：预期行为 → 实际行为 → 复现步骤
  3. 包含信息：环境信息、Severity、截图/日志、业务影响
  4. 定位范围：缩小触发条件（如浏览器、用户群体、金额阈值等）
  5. 一Bug一报告（请勿合并多个问题）
Bug报告模板：
markdown
undefined

[Component] Issue Title

[Component] Issue Title

Severity: Critical/High/Medium/Low Environment: Production/Staging/Dev
Severity: Critical/High/Medium/Low Environment: Production/Staging/Dev

Expected Behavior

Expected Behavior

What should happen
What should happen

Actual Behavior

Actual Behavior

What actually happens (with error messages)
What actually happens (with error messages)

Steps to Reproduce

Steps to Reproduce

  1. Step one
  2. Step two
  3. Observe issue
  1. Step one
  2. Step two
  3. Observe issue

Impact

Impact

How this affects users/business

**Critical Success Factors:**
- Reproducible steps (100%)
- Environment info (100%)
- Business impact stated (90%)
- Screenshots or logs (80%)
</default_to_action>
How this affects users/business

**关键成功要素：**
- 可稳定复现的步骤（100%）
- 完整的环境信息（100%）
- 明确说明业务影响（90%）
- 附带截图或日志（80%）
</default_to_action>

Quick Reference Card

快速参考卡片

Severity Levels

严重程度等级

LevelDefinitionExamples
CriticalSystem down, data loss, securityDB deleted, payments broken, credentials exposed
HighMajor feature broken, many usersCan't checkout, search broken, dashboard fails
MediumPartial break, workaround existsFilter broken (refresh works), slow export
LowCosmetic, rare edge caseButton wraps on mobile, tooltip wrong color
等级定义示例
Critical系统宕机、数据丢失、安全问题数据库被删除、支付功能故障、凭证泄露
High核心功能故障，影响大量用户无法完成结账、搜索功能失效、仪表盘无法加载
Medium功能部分失效，存在替代方案筛选功能故障（刷新可恢复）、导出速度缓慢
Low界面瑕疵、罕见边缘场景问题移动端按钮换行、提示框颜色错误

Title Formula

标题模板

❌ Bad: "Checkout broken" ✅ Good: "Payment fails with Visa cards when order total > $1000"
Pattern: 
[Component] fails [Condition] causing [Impact]
❌ 错误示例：「结账功能坏了」 ✅ 正确示例：「当订单金额超过1000美元时，Visa卡支付失败」
模板： 
[Component] fails [Condition] causing [Impact]

Essential Information

核心信息

Environment Details

环境详情

Browser: Chrome 120.0.6099.109 (Windows)
OS: Windows 11 Pro
URL: https://example.com/checkout
Date/Time: 2025-10-17 14:23 UTC
User: test@example.com (ID: 12345)
Request ID: abc-123-def-456
Browser: Chrome 120.0.6099.109 (Windows)
OS: Windows 11 Pro
URL: https://example.com/checkout
Date/Time: 2025-10-17 14:23 UTC
User: test@example.com (ID: 12345)
Request ID: abc-123-def-456

Supporting Evidence

佐证材料

Error Messages:
json
{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}
Console Logs:
[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)
错误信息：
json
{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}
控制台日志：
[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)

Example: Excellent Bug Report

示例：优质Bug报告

markdown
undefined
markdown
undefined

[Checkout] Payment processing times out for orders > $1000

[Checkout] Payment processing times out for orders > $1000

Severity: High Environment: Production Affected Users: ~15% of premium purchases
Severity: High Environment: Production Affected Users: ~15% of premium purchases

Expected Behavior

Expected Behavior

Payment completes within 5 seconds regardless of amount.
Payment completes within 5 seconds regardless of amount.

Actual Behavior

Actual Behavior

For orders above $1000, payment gateway times out after 30 seconds. User sees "Payment failed" error. Order not created.
For orders above $1000, payment gateway times out after 30 seconds. User sees "Payment failed" error. Order not created.

Steps to Reproduce

Steps to Reproduce

  1. Add items totaling $1,050 to cart
  2. Proceed to checkout
  3. Enter payment: Visa 4532 1234 5678 9010
  4. Click "Place Order"
  5. Wait 30+ seconds
  6. Observe timeout error
  1. Add items totaling $1,050 to cart
  2. Proceed to checkout
  3. Enter payment: Visa 4532 1234 5678 9010
  4. Click "Place Order"
  5. Wait 30+ seconds
  6. Observe timeout error

Environment

Environment

  • Browser: Chrome 120 (Windows 11)
  • User: test@example.com
  • Request ID: abc-123-def-456
  • Browser: Chrome 120 (Windows 11)
  • User: test@example.com
  • Request ID: abc-123-def-456

Evidence

Evidence

Console error: 
PaymentGateway timeout: 30000ms exceeded
Network: /api/checkout: 30.14s (timeout)
Console error: 
PaymentGateway timeout: 30000ms exceeded
Network: /api/checkout: 30.14s (timeout)

Impact

Impact

  • Lost revenue: ~$15K/week from failed orders
  • 23 support tickets this week
  • Affects 15% of orders over $1000
  • Lost revenue: ~$15K/week from failed orders
  • 23 support tickets this week
  • Affects 15% of orders over $1000

Additional Context

Additional Context

Started after Oct 15 deployment (v2.3.0) Possibly related to PR #456 (fraud check)

---
Started after Oct 15 deployment (v2.3.0) Possibly related to PR #456 (fraud check)

---

Anti-Patterns

反模式示例

❌ BadProblem✅ Good
"Checkout is broken"What doesn't work?"Payment button doesn't respond when clicked"
"I saw an error"No reproduction stepsFull steps with conditions
"Page loads slowly"No specifics"Dashboard takes 12s to load (should be <3s)"
Multiple bugs in oneCan't track separatelyOne report per bug
❌ 错误示例问题✅ 正确示例
「结账功能坏了」未明确具体故障点「点击支付按钮无响应」
「我遇到了一个错误」未提供复现步骤完整的复现步骤及触发条件
「页面加载缓慢」无具体细节「仪表盘加载需12秒（预期应小于3秒）」
一份报告包含多个Bug无法单独跟踪一个Bug对应一份报告

Agent Integration

Agent集成

typescript
// Automated bug triage
const triage = await Task("Triage Bug", {
  title: 'Payment fails for orders > $1000',
  description: bugDescription,
  steps: reproductionSteps
}, "qe-quality-analyzer");

// Returns: { severity, priority, component, suggestedAssignee, relatedIssues }

// Duplicate detection
const dupeCheck = await Task("Check Duplicates", {
  bugReport: newBug,
  similarityThreshold: 0.85
}, "qe-quality-analyzer");

// Bug report enhancement
const enhanced = await Task("Enhance Report", {
  originalReport: userSubmittedBug,
  addMissingInfo: true,
  identifyRootCause: true
}, "qe-production-intelligence");
typescript
// Automated bug triage
const triage = await Task("Triage Bug", {
  title: 'Payment fails for orders > $1000',
  description: bugDescription,
  steps: reproductionSteps
}, "qe-quality-analyzer");

// Returns: { severity, priority, component, suggestedAssignee, relatedIssues }

// Duplicate detection
const dupeCheck = await Task("Check Duplicates", {
  bugReport: newBug,
  similarityThreshold: 0.85
}, "qe-quality-analyzer");

// Bug report enhancement
const enhanced = await Task("Enhance Report", {
  originalReport: userSubmittedBug,
  addMissingInfo: true,
  identifyRootCause: true
}, "qe-production-intelligence");

Agent Coordination Hints

Agent协作提示

Memory Namespace

内存命名空间

aqe/bug-reports/
├── triaged/*          - Bug triage results
├── duplicates/*       - Duplicate detection
├── patterns/*         - Recurring bug patterns
└── root-cause/*       - Root cause analyses
aqe/bug-reports/
├── triaged/*          - Bug triage results
├── duplicates/*       - Duplicate detection
├── patterns/*         - Recurring bug patterns
└── root-cause/*       - Root cause analyses

Fleet Coordination

集群协作

typescript
const bugFleet = await FleetManager.coordinate({
  strategy: 'bug-investigation',
  agents: [
    'qe-quality-analyzer',        // Triage and categorize
    'qe-flaky-test-hunter',       // Check if test-related
    'qe-production-intelligence'  // Check production logs
  ],
  topology: 'parallel'
});
typescript
const bugFleet = await FleetManager.coordinate({
  strategy: 'bug-investigation',
  agents: [
    'qe-quality-analyzer',        // Triage and categorize
    'qe-flaky-test-hunter',       // Check if test-related
    'qe-production-intelligence'  // Check production logs
  ],
  topology: 'parallel'
});

Related Skills

相关技能

  • technical-writing - Clear bug documentation
  • exploratory-testing-advanced - Finding bugs
  • sherlock-review - Root cause investigation
  • technical-writing - 清晰的Bug文档撰写
  • exploratory-testing-advanced - Bug排查
  • sherlock-review - 根因分析

Remember

注意事项

Your bug report is the starting point for someone else's work. Make it complete (all info needed), clear (anyone can follow), concise (no noise), and actionable (developer knows next step).
Good bug reports = Faster fixes = Better product = Happier users
你的Bug报告是他人开展工作的起点，请确保报告完整（包含所有必要信息）、清晰（任何人都能理解）、简洁（无冗余内容）且可执行（开发人员明确下一步工作）。
优质Bug报告 = 更快的修复速度 = 更优的产品 = 更满意的用户