SKILL.md
Writing issues
REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).
Overview
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.
Read-first applies to 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: