Writing issues

REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).

Overview

An issue is read months later by someone who was not in the conversation, including you. Core principle: write issues so they survive without you. State the outcome, include the acceptance check that decides Done, link the evidence behind every decision, and name the owner of every open part.

When to invoke, and not

Invoke when writing or editing tracker items, filing a bug, splitting work into tickets, or writing acceptance criteria. Do NOT invoke for weighing alternatives: when an issue needs a design argued, that is writing-design-docs; the issue links the design doc and never inlines it. This skill covers the writing only, not prioritization or workflow advice.

The read-first rule here means the tracker: read up to two recent issues of the same type and match their conventions before filing. When the tracker holds fewer, read what exists and file anyway.

When the reporter is unavailable, file with named gaps rather than blocking. The technical-writing checkpoint (kind, audience, purpose, non-goals) is what you stop and ask about. Missing content details (a repro step, a log line, a prior-incident link) become explicitly owned open items inside the issue.

The survives-without-you test

Every issue answers four questions a stranger will ask: