writing-issues

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:

1. What outcome? The state of the world when this is done, not the steps to get there. Implementation belongs in the plan; an issue that prescribes the implementation is stale the moment a better approach appears.
2. What decides Done? A concrete, independently testable acceptance check. "Handle errors appropriately" decides nothing; "a failed upload shows the retry banner and logs at WARN" does.
3. What is the evidence? Where a decision or constraint came from evidence, link the source: a repo path, a document, a URL. A claim with no source is relitigated later.
4. Who owns the open parts? "Still needs investigation" without a name or role is a banned vague owner; name one or mark the field explicitly as unassigned.