File an issue

An issue is read by someone who was not there when the problem was found, often months later. Every bar below exists so that reader can act on it without coming back to ask what it meant.

1. Confirm this is one issue

One issue carries one observable problem and one acceptance condition.

Work that splits into several tickets with blocking edges between them belongs to to-tickets. A spec synthesised from the current conversation belongs to to-spec. Hand off rather than filing a container ticket that hides its real scope.

The gate is simple. The scope is one problem with one acceptance condition, or the work is handed off by name.

2. Search before filing

gh issue list --repo "$repository" --search "<the symptom in your words>" --state all --limit 20
gh issue list --repo "$repository" --search "<the symptom in the reporter's words>" --state all --limit 20