| name | issue-authoring |
| description | Use when creating, writing, or drafting a GitHub issue. Covers tone, conciseness, detail, scope, and audience-fit — not investigation or gh mechanics. |
Issue Authoring
Guidelines for writing a good GitHub issue. Assumes investigation is done
(use codebase-exploration / gh-cli for that) and mechanics are handled
(gh-cli covers gh issue create --body-file).
Principles (always apply)
-
Sound human. Write prose with voice, not stacked headers of corporate
hedging. Read it aloud — if it sounds bot-generated, rewrite. "We've decided
to remove the integration" beats "This issue proposes the removal of...".
-
Concise and decisive. State what matters; cut the rest. Don't over-cite
or over-justify — one telling detail beats a table of every supporting fact.
If a reader needs the full evidence, link it; don't reproduce it.
-
Match detail to purpose. A chore wants action (checklist). A discussion
or spike wants findings. Don't dump investigation output into a task that
wants a handoff — and don't force a checklist onto an open question.
-
Be scope-honest. If something looks in-scope but belongs elsewhere, say
so and defer it with a link. Scope creep turns a good first issue into a
trap for the contributor who picks it up.
Audience
State the audience before writing — it sets tone, assumed context, detail, and
labels. Match the row; let it steer the draft.
| Audience | Tone | Detail | Labels |
|---|
| Contributor pickup | Direct, actionable; assume less context | Task as checklist; flag maintainer-only steps; defer out-of-scope with links | help wanted, good first issue (only if truly scoped & trap-free) |
| Maintainer sync | Terse; assume shared context | Just the decision/change; skip background | usually none |
| Bug triage | Neutral, reproducible | Description + repro + expected/actual + env | bug |
| Discussion / spike | Open, exploratory | Findings + open questions; no forced checklist | enhancement / feature request |
Self-check (run over the draft before creating)
- Human? Read it aloud. Bot-sounding? Rewrite.
- Earns its place? Any over-citing or over-justifying to cut?
- Detail matches purpose? Action for chores, findings for discussions?
- Scope-honest? Anything smuggled in that belongs in another issue? Link & defer.
- Right audience default? Tone and labels match who will read it?
- Labels honest?
good first issue only if genuinely scoped and trap-free.
