issue-hygiene

Stars12

Forks0

UpdatedJune 20, 2026 at 02:33

Use when creating, editing, triaging, or cleaning up GitHub issues - a mechanical pass that verifies the title is accurate and current, labels/assignees/milestone are correct, and the body is valid, well-formed markdown, all via the gh CLI. Does not judge content quality.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

pbdeuchler

pbdeuchler/llm-plugins

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	issue-hygiene
description	Use when creating, editing, triaging, or cleaning up GitHub issues - a mechanical pass that verifies the title is accurate and current, labels/assignees/milestone are correct, and the body is valid, well-formed markdown, all via the gh CLI. Does not judge content quality.

GitHub Issue Hygiene

Overview

A mechanical hygiene pass over a GitHub issue: correct title, correct labels and metadata, valid markdown body. This is the lint layer - it does NOT judge whether the issue is well-reasoned or complete (that is authoring-issues). Run it after drafting an issue, or when asked to tidy or triage existing ones.

All edits go through the gh CLI. Verify current state before changing anything, and change only what is wrong (minimal edits).

When to Use

Creating or editing an issue and about to finalize it.
User asks to "clean up", "triage", "retitle", "tag", "label", or "fix up" an issue.
Immediately after authoring-issues produces a draft.
Bulk triage of a backlog.

The Checklist

Title

Reflects the CURRENT body. If the scope changed, update the title to match.
Concise and specific, imperative or noun-phrase. No trailing period.
Follow the repo's existing prefix convention if one exists (e.g. area:, [component]) - check sibling issues first; do not invent one.

Labels and metadata

List the repo's real labels first: gh label list. NEVER apply a label that does not exist unless explicitly asked to create one.
Apply at least a type (bug/feature/chore/...) and an area/component label when those label families exist.
Set assignee, milestone, and project only when known; do not guess.
Link related work in the body: Closes #N, Refs #N. Mark duplicates.

Body markdown

Headings nest correctly (no skipped levels); use sentence case.
Every fenced code block is closed and language-tagged.
Lists and task lists are well-formed (- [ ] / - [x]); tables have aligned header separators.
Links and #issue / @user references resolve.
No placeholder or broken text left behind.

Commands

gh issue view <n> --json title,body,labels,assignees,milestone
gh label list                                   # real labels before tagging
gh issue edit <n> --title "..." \
  --add-label bug --add-label "area:api" \
  --milestone "v1.2"
gh issue create --title "..." --body-file draft.md --label bug

Render-check the body (gh issue view <n> --web, or preview the markdown) before declaring done.

Red Flags - Stop

Inventing a label or milestone that does not exist in the repo.
Rewriting the body's CONTENT to "improve" it - that is authoring-issues, not hygiene.
Altering meaning while "fixing markdown".
Leaving the title describing an older version of the body.

More from this repository

same repository

holistic-review

pbdeuchler/llm-plugins

Use when reviewing a completed implementation holistically - a finished branch, a completed plan step, or a diff before PR. Reviews every changed line against the implementation plan (if one exists) and high engineering standards across seven dimensions, verifies tests by deliberately breaking crucial code, and emits severity-classified findings with a PASS/FAIL verdict.

2026-07-0312

holistic-review

pbdeuchler/llm-plugins

Use when performing a holistic code review of an implementation - routes to codex:rescue or falls back to a direct subagent, both running the house-style:holistic-review skill

2026-07-0312

coding-effectively

pbdeuchler/llm-plugins

ALWAYS use before any implementation work, review, or planning: designing, writing, editing, refactoring, debugging, reviewing, or generating source code, tests, scripts, config-as-code, or behavior-affecting files. This is a baseline engineering skill and should be invoked even when a more specific language, framework, testing, or database skill also applies.

2026-06-2212

authoring-issues

pbdeuchler/llm-plugins

Use when asked to write, draft, file, or open a GitHub issue - mandates exploring the relevant code to understand the whole problem space, reasoning any proposed solution, and structuring the issue with summary, what/why, references, nuances, open questions, and acceptance criteria. Adds professionalism and no-sensitive-info discipline for public repos.

2026-06-2012

howto-uv

pbdeuchler/llm-plugins

Use when running Python, installing Python packages, creating virtualenvs, or executing Python CLI tools - mandates uv/uvx over direct python/pip/pipx/venv calls when uv is installed, and gives the drop-in command mappings

2026-06-1612

lift-the-reference

pbdeuchler/llm-plugins

Use when the user provides a reference implementation (URL, repo path, branch, file) plus a verb like "use", "copy", "adapt", "port", "model after" - mandates fetching/reading the reference before designing, and lifting the structure rather than reimagining it.

2026-05-1912

name	issue-hygiene
description	Use when creating, editing, triaging, or cleaning up GitHub issues - a mechanical pass that verifies the title is accurate and current, labels/assignees/milestone are correct, and the body is valid, well-formed markdown, all via the gh CLI. Does not judge content quality.

GitHub Issue Hygiene

Overview

All edits go through the gh CLI. Verify current state before changing anything, and change only what is wrong (minimal edits).

When to Use

Creating or editing an issue and about to finalize it.
User asks to "clean up", "triage", "retitle", "tag", "label", or "fix up" an issue.
Immediately after authoring-issues produces a draft.
Bulk triage of a backlog.

The Checklist

Title

Reflects the CURRENT body. If the scope changed, update the title to match.
Concise and specific, imperative or noun-phrase. No trailing period.
Follow the repo's existing prefix convention if one exists (e.g. area:, [component]) - check sibling issues first; do not invent one.

Labels and metadata

List the repo's real labels first: gh label list. NEVER apply a label that does not exist unless explicitly asked to create one.
Apply at least a type (bug/feature/chore/...) and an area/component label when those label families exist.
Set assignee, milestone, and project only when known; do not guess.
Link related work in the body: Closes #N, Refs #N. Mark duplicates.

Body markdown

Headings nest correctly (no skipped levels); use sentence case.
Every fenced code block is closed and language-tagged.
Lists and task lists are well-formed (- [ ] / - [x]); tables have aligned header separators.
Links and #issue / @user references resolve.
No placeholder or broken text left behind.

Commands

gh issue view <n> --json title,body,labels,assignees,milestone
gh label list                                   # real labels before tagging
gh issue edit <n> --title "..." \
  --add-label bug --add-label "area:api" \
  --milestone "v1.2"
gh issue create --title "..." --body-file draft.md --label bug

Render-check the body (gh issue view <n> --web, or preview the markdown) before declaring done.

Red Flags - Stop

Inventing a label or milestone that does not exist in the repo.
Rewriting the body's CONTENT to "improve" it - that is authoring-issues, not hygiene.
Altering meaning while "fixing markdown".
Leaving the title describing an older version of the body.