github-authoring

# GitHub authoring The authoring standard for every issue, PR, and commit in this repo. Two parts: how the text is structured, and how it reads. This applies to text authored by an agent and by the repo owner alike. ## When to apply Whenever composing the body or title of: - A GitHub issue - A pull request - A commit message ## Structure Pick the structure that fits the content. The defaults: - **Headings** to separate sections (What, Why, How, etc.). - **Bullet lists** for unordered points; **numbered lists** for ordered steps. - **Tables** for comparisons (option A vs option B, before vs after, layer-by-layer). - **Fenced code blocks** for commands, diffs, and config. Never inline a multi-line command in prose. ### Bug reports: the "what is the bug" block A bug issue states three things explicitly: ```text Repro: the exact steps or command that triggers it Observed: what actually happens Expected: what should happen instead ``` Without all three, a reader cannot confirm the bug or verify a fix. Include the version, environment, or commit when they affect the repro. ### Features: before/after A feature issue or PR shows the change as before/after. A table or two fenced blocks both work: | Before | After | |---|---| | current behavior | new behavior | State what the user could not do before and can do after. ## Voice - **Factual and technical.** State facts, not their importance. Write "the parser drops unquoted `: ` in descriptions," not "the parser has a serious problem with descriptions." - **No emdashes.** Use a colon, a comma, parentheses, or two separate sentences instead. The emdash is the one punctuation mark this repo does not use in authored GitHub text. - **No editorializing labels.** Drop "(critical)", "the key part", "the important bit", "note that", and similar. If a point matters, the fact carries it; the label adds nothing a reader can act on. - **Never use the term "load bearing."** State what the thing does and what breaks without it, in plain terms. ## Titles and labels Naming and the label taxonomy are defined in [`issue-pr-conventions`](../issue-pr-conventions/SKILL.md). What matters while authoring: - Every title takes a conventional-commit prefix: `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`, `perf:`, `build:`. Append `!` for a breaking change. This applies to issue titles as much as to commits and PRs. - A PR title closing an issue names it: `(closes #N)`. - There is no type label. The prefix is the only record of an item's type, so an unprefixed title is unfindable by type. - Never apply `good first issue` or `help wanted`. PR-farming accounts scrape GitHub's global feed of newly labeled beginner issues and open drive-by PRs within minutes: filing an audit backlog with these labels drew a burst of bot PRs to a private repo inside half an hour, with a label-to-PR latency around 30 minutes. If a human added one, leave it in place. ## Commits: no trailers, author is the repo owner - Do not add a `Co-Authored-By` trailer. - Do not add a "Generated with Claude Code" trailer. - The commit author is always the repo owner. After committing, verify: ```bash git log -1 --format='%an <%ae>' # repo owner git log -1 --format='%(trailers)' # empty ``` If a trailer appears, amend it out before pushing (`git commit --amend` and remove the trailer line). ## Anti-patterns - A `good first issue` or `help wanted` label on an issue (a PR-farming-bot magnet). - A type label (`feat`, `bug`, `enhancement`) restating the title prefix. - Emdashes anywhere in the authored body or title. - Editorializing labels like "(critical)" or "the key part." - The phrase "load bearing." - A multi-line command pasted into prose instead of a fenced block. - A bug report missing repro, observed, or expected. - A commit carrying a `Co-Authored-By` or "Generated with Claude Code" trailer. - A title without a conventional-commit prefix. ## Related - [`issue-pr-conventions`](../issue-pr-conventions/SKILL.md): the naming scheme and label taxonomy these bodies sit on. - [`git-branch-pr-workflow`](../git-branch-pr-workflow/SKILL.md): the branch + PR discipline these titles and bodies ride on. - [`triage`](../triage/SKILL.md): labels the issues this skill helps author. - [`heredoc-backticks`](../heredoc-backticks/SKILL.md): keeps the fenced blocks rendering when a body is piped through a single-quoted heredoc into `gh`.