bug-from-user

When to use

• A user has reported a problem in prose (email, Discord, Twitter DM, support ticket).
• The dev cannot tell from the message:
  • what was expected vs. what actually happened
  • the steps to reproduce
  • whether it's a real bug, user error, or a feature request in disguise
• The dev wants a GitHub issue or internal note they can later sit down and fix.

When NOT to use

• The user has already produced a clean, reproducible report. Don't re-process it.
• The complaint is subjective ("it's slow", "it's ugly") with no measurable claim — that's a UX or perf investigation, not a bug.
• The user is asking for a feature (e.g. "can you add X?") — file as feature request, not bug.

The four-question conversion

For any prose complaint, reduce it to:

1. Trigger — what did the user do (action, click, command, input)?
2. Expected — what did they expect to happen?
3. Actual — what actually happened?
4. Surface — where did it happen (URL, screen, version, browser, OS)?

If any of the four is missing, flag it as a follow-up question rather than guessing.

Output format

### Bug: <one-sentence headline, user-perspective>

**Trigger:**
1. <step>
2. <step>

**Expected:** <what they expected>

**Actual:** <what actually happened>

**Surface:** <version / browser / OS / URL>

**Confidence:** <high | medium | low>
- high: report is self-contained, can repro from this alone
- medium: 1–2 reasonable assumptions made
- low: significant guessing — ask user to confirm

**Follow-ups (if any):**
- <question to ask the user>

Worked example

Input (raw user email):

"hey i tried buying the pro plan tonight and the website just kept loading forever, i refreshed a few times then gave up. using safari on my macbook"

Output:

### Bug: Pro plan checkout hangs on Safari (macOS)

**Trigger:**
1. Visit pricing page on Safari (macOS).
2. Click "Pro plan" purchase button.
3. Observe checkout flow.

**Expected:** Stripe checkout opens within a few seconds.

**Actual:** Page stays in loading state indefinitely; refresh does not recover.

**Surface:** Safari on macOS. Version of Safari and macOS unknown. Pricing page URL unknown (likely /pricing).

**Confidence:** medium
- Assumed pricing page URL is /pricing.
- Assumed checkout uses Stripe.

**Follow-ups:**
- Which Safari version + macOS version?
- Does Chrome on the same machine reproduce it?
- Browser console errors (if comfortable opening DevTools)?

Anti-patterns to avoid

• Don't assume severity — "P0 outage" without evidence is alarmist.
• Don't guess root cause in the report — that's the dev's job after reading. The report describes symptoms.
• Don't promise a fix timeline — that goes in the reply email, not the bug report.

---

中文版

何时使用

• 用户用散文报了一个问题（邮件、Discord、推特 DM、工单）。
• 看不出：
  • 期望 vs 实际
  • 复现步骤
  • 是真 bug、用户操作问题、还是变相的功能请求

何时不使用

• 用户已经写好了清晰可复现的报告——别重新加工。
• 抱怨是主观的（"慢"、"丑"），没有可测指标——那是 UX/性能调研，不是 bug。
• 用户是要功能——按 feature request 处理。

四问转化法

把任何散文压成 4 个问题：

1. 触发——用户做了什么动作？
2. 期望——他们期望发生什么？
3. 实际——实际发生了什么？
4. 环境——在哪里发生（URL、屏幕、版本、浏览器、系统）？

任意一项缺失 → 列为待问，不要猜。

输出

### Bug: <一句话标题，用户视角>

**触发：**
1. <步骤>
2. <步骤>

**期望：** <…>

**实际：** <…>

**环境：** <…>

**置信度：** <high | medium | low>

**待问：**
- <…>

反模式

• 不要乱定优先级——没证据就"P0"是恐慌。
• 不要在报告里猜根因——根因是开发读完之后的事，报告只描述现象。
• 不要承诺修复时间——那写在回复邮件里，不写在 bug 单里。