github-issues

---
name: github-issues
description: Working with GitHub issues and PRs in this repo via the gh CLI. Use when creating, viewing, commenting on, or labeling issues, planning work, opening a PR, or referencing an issue from a commit.
---

# GitHub Issues

Use the `gh` CLI. Check open issues before creating to avoid duplicates:
`gh issue list --state open`

## Conventions

- Create an issue for new work, plans, or bugs:
  `gh issue create --title "GPU power cap plan" --body "$(cat plan.md)" --label enhancement`
- Titles: short outcome phrase, no trailing period (e.g. "GPU power cap plan").
- Labels (apply when it fits; plain to-dos may stay unlabeled):
  bug → `bug`, feature → `enhancement`, docs → `documentation`, lessons/postmortems → `lessons`.
  Add later: `gh issue edit 21 --add-label lessons`
- Commit messages (written by the user) reference the issue as `(#N)`. Suggest messages that way; do NOT use `Closes`/`Fixes` keywords — they auto-close the issue on merge.

## Issue templates

- Plan/investigation issues: Background → Findings → Decisions → Execution Steps → Deliverables → Revert.
- Bug issues: what happened, environment (OS/driver/CUDA/model), repro steps, expected vs actual.

## Day-to-day

- Read an issue: `gh issue view 21`
- Note progress in a comment: `gh issue comment 21 --body "Applied 165W cap, results pending"`
- Plan changed mid-work? Update the body: `gh issue edit 21 --body "$(cat updated-plan.md)"`

## Delivery and closing

- NEVER stage (`git add`), commit, or push — leave all git mutations to the user so they can review work before it is committed. Work happens on the current branch if it is not `main` (do not create a new branch per ticket). When work is ready, hand off with a suggested commit message and the PR command for the user: `gh pr create --base main --title "Short outcome phrase" --body "Work for #N"` — then stop.
- The owner reviews and merges the PR; only after that may the issue be closed, and by the owner — not you. NEVER close an issue yourself (no `gh issue close`, no closing keywords anywhere).
- Batching: multiple tickets (e.g. a set of `newtech` items) are handled on the same branch — the user commits one commit per ticket; one PR per batch references all issues (`Work for #85, #86`).
- Rejections: label `wontfix`, `duplicate`, or `invalid` and comment why; closing is left to the owner.