Writing tickets
An issue says what is left to do. The spec says what should be true. Keeping
those apart is the whole job.
Read the project's conventions first
Labels, templates and title format are per-project and guessing them produces a
ticket someone has to correct by hand:
ls .github/ISSUE_TEMPLATE/ .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
gh label list --limit 100
git log --oneline -20
Many projects also keep a ticket doc (docs/TICKETS.md, CONTRIBUTING.md) that
states which label axes are required and what the board columns mean. Read it
before opening anything; it outranks this skill.
Never copy spec text
Link the requirement, do not restate it. Copies rot, and the moment they disagree
nobody knows which one is the product.
Implements: LIB-4, LIB-7
Resolve an ID to its chapter through the spec's index. If the behaviour has no
requirement yet, the spec change comes first: use the spec-writing skill, then
open the issue against the new ID. Where the project keeps no spec, state the
intended behaviour in the ticket and accept that the ticket is now the record.
Structure
Where the project runs epics, each domain has one long-lived epic issue and
implementation work is opened as a sub-issue of it, so the board rolls up
without anyone maintaining a checklist by hand.
A sub-issue is one story: one requirement, one reviewable change, one PR. Work
that needs three PRs is three sub-issues.
Labels
Take the axes from gh label list and the project's ticket doc, not from memory.
The common shape is one namespaced axis for the kind of work, one for urgency, and
one or more for where in the stack it lands, plus a couple of flow labels for
waiting rather than working.
Two mistakes worth naming, because both are easy and both are wrong:
- Assuming an axis is optional because you did not see it. A project with a
priority axis expects one on every ticket, and a triager has to add it later.
- Assuming two axes mean the same thing. A stack area and a product domain are
different vocabularies that happen to share a word or two. Map to whichever one
the label list actually holds.
Leave the automation's labels alone. Dependency and language labels are usually
applied by a bot, and applying them by hand fights it.
What a good ticket carries
- What needs doing, in the reader's terms, not the implementation's.
- Why now. What it unblocks, or what it costs to keep not doing it. "It
bothers me" is a real reason, written down.
- Done when. The observable condition. If you cannot name one, the ticket is
not ready and probably wants the project's discussion label instead.
Title: <surface>: <imperative summary>, lower case, no trailing full stop.
ci: cache cargo builds between release jobs reads right. Fix the CI does not.
Leave the design out unless it is the point. A ticket that dictates the patch
removes the reason to have an engineer read it.
Security
Never open a public issue for a vulnerability. It goes through the project's
private channel: a security advisory, the address in SECURITY.md, or the contact
link the issue chooser offers.
PR descriptions
Open the project's PR template and answer every section it asks for. The four that
recur, and the real answer to each:
- What: one paragraph, what changes and why this way rather than another.
- Closes:
Closes #123, or "no issue" and a sentence on why it did not need one.
- Checks: the boxes are claims. Tick one only after running the command it
names, and where one failed, say which and why rather than leaving it unticked
in silence.
- Risk: what breaks if this is wrong, and how a reviewer would notice. "None,
it is a docs typo" is a fine answer.
Where the project squash-merges, the PR title becomes the commit on the default
branch, so it follows whatever commit convention git log shows.
Run the unslop skill over the body before opening. A PR description is the
most-read prose in a repository and the most likely to arrive padded.