Skip to content

Instantly share code, notes, and snippets.

@simonholm

simonholm/tech-issue-reporting.md

Created November 12, 2025 07:25
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save simonholm/2bd922f39adff1e6e1dcc267a7e2415b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save simonholm/2bd922f39adff1e6e1dcc267a7e2415b to your computer and use it in GitHub Desktop.
Download ZIP
Tech issue reporting guide
Raw
tech-issue-reporting.md

Quick Tech Issue Reporting Guide

The Problem

Vague reports like "status issues" or "operational disturbance" require multiple clarification rounds.

Solution Pattern

Subject + Specific Problem

Examples

Service Status Queries

  • BAD: "status issues, like yesterday"
  • GOOD: "Is Claude.ai down?"
  • GOOD: "Claude.ai service status?"
  • GOOD: "Anthropic outage check?"

System Issues

  • BAD: "having problems"
  • GOOD: "MCP servers - not responding in Desktop"
  • GOOD: "WSL - disk full errors"
  • GOOD: "Backup script - failing on line 47"

Standard Tech Terminology

Service Availability

  • Outage - complete service failure
  • Downtime - period when service unavailable
  • Service disruption - partial failures or degraded performance
  • Degraded performance - slow but working
  • Incident - official term on status pages

Avoid

  • "Operational disturbance" (uncommon, sounds corporate)
  • Ambiguous subjects that could mean multiple systems
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment