to-issues-clearly

To issues clearly

Turn a plan, bug report, audit finding, or PRD into live GitHub issues that explain the outcome clearly enough for another person to implement and verify.

The tracker is the publication surface. Draft in the conversation, then create or edit the issue directly with GitHub. The skill supplies judgment and a repeatable shape; GitHub supplies the issue number, labels, and relationships.

The title is the whole job

Everything else here is ordinary. This part is not, because it fails constantly and always looks fine at the time.

The shape

A title has two halves: what somebody wrote, asked for, or did — then what the system did with it.

A config can set retries to five, and the client gives up after three
A user can mark an invoice paid, and the balance does not move
A migration can declare a rollback, and it is never run
A CLI flag can ask for JSON, and it prints a table

The first half does the work. It forces you to name something a real person actually does, and you cannot write it about a mechanism, because mechanisms are not written by anyone. Most bad titles die right there — there is nothing to put in the first half.

When nobody wrote anything and the thing simply misbehaves, the first half is the action that sets it off:

Deleting the last admin leaves the account with no owner
Retrying a failed upload uploads it twice

Not a state of affairs, and not a description of code. Something a person does, then what came of it.

Every word must survive a stranger

A word that exists only inside your codebase costs the reader a lookup. Two of them and the title is unreadable, however plain each one looks on its own.

rule, tag, arm, node, handler, resolver, context, entry, record are all concrete nouns and all internal. Replace each with the thing it stands for in the world the software is about — an invoice, a retry, a login, a status.

This is the one that is easiest to think you passed. Read only the title, and for each noun ask: would somebody who has never opened this repository know what it refers to? Not "could they guess". Know.