writing-issues

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: writing-issues
description: Use when writing or refining tracker items - epics, stories, tasks, bug reports, spikes, or acceptance criteria - or when turning a discussion, review finding, or plan into tickets. Encodes the survives-without-you test, the issue-type glossary, and the story and bug skeletons. Use whenever work is written into a tracker, even from a rough verbal dump.
---

# 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:

1. **What outcome?** The state of the world when this is done, not the steps to get there. Implementation belongs in the plan.
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.
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.

## Issue types

One glossary per tracker, defined in one line each and used consistently:

| Type | Definition |
|---|---|
| Epic | A body of work; its description states the outcome and links the design doc |
| Story | Something with user-visible value, written from the user's seat |
| Task | Engineering work with no user-visible surface |
| Bug | A defect: current behavior contradicts intended behavior |
| Spike | A time-boxed investigation whose output is a decision, not code |

A spike's Done is the decision recorded (see `recording-decisions`), never "looked into it".

A decision followed by a body of work fits two shapes: a spike first with the epic filed after the decision, or an epic whose first acceptance item is the accepted design doc. Both are valid; pick one and say which.

## Story and task skeleton

The issue description is the spec for what and why:

```markdown
**Problem / Why:** [the observable problem, from the reader's seat, with numbers where they exist]

**Outcome:** [the state of the world when done; not the steps]

**Acceptance:**
- [ ] [independently testable check]
- [ ] [another]

**Out of scope:** [what this issue deliberately does not cover]

**Open items:** [each with a named owner or role, or an explicit "unassigned"]

**Sources:** [repo paths, documents, measurements behind the above]
```

Apply the five vagueness defects from `writing-design-docs` to the acceptance list: an acceptance check that fails "what without how" or "no verifiable output" is not testable.

Gherkin-style given/when/then is an accepted format for acceptance checks when the team uses it; the same testability bar applies either way. INVEST (independent, neg