Extract facts before writing the issue title
Read the complete conversation, including agent questions, attachments, internal notes, and timing. Identify what the customer attempted, what they expected, what occurred, how often it happened, which environment was involved, and what consequence followed.
Keep quotes or source links for important claims. Rewrite sensitive or verbose material into a focused summary only after the source is retained under the appropriate access controls.
- Customer role, plan, tenant, device, browser, version, and locale when relevant.
- The smallest known sequence that produces the behavior.
- Screenshots, recordings, request identifiers, timestamps, logs, or traces.
- Workaround and whether it is acceptable for the affected customer.
- First occurrence, latest occurrence, and any known change before onset.
Write a behavioral problem statement
A useful title names the product behavior and failure mode, not the customer or a speculative root cause. The opening statement should identify who encounters the problem, under which condition, and what outcome fails.
For example, prefer a statement such as ‘Workspace admins cannot export audit logs when a date range crosses month boundaries’ over ‘Export service date parser is broken.’ The first is testable from customer evidence. The second may later become a validated technical explanation.
Add scope and impact without exaggeration
Separate confirmed reports from suspected exposure. List affected accounts or segments, number of independent occurrences, severity of the customer outcome, commercial context, and confidence. Do not multiply ticket replies into additional customers.
State whether the evidence points to a single environment, plan, role, integration, data shape, or release. Also state what appears unaffected. Negative evidence can prevent engineering from investigating an unnecessarily broad surface.
Define acceptance and verification separately
Acceptance criteria describe what must be true for the proposed work to meet the intended product behavior. Verification explains how the team will confirm that behavior after implementation and release.
Include the original reproduction case, relevant regression cases, production signals, and an observation window. When appropriate, ask an affected customer to retest after the team has confirmed availability and communication permissions.