cuga-github-issues

CUGA GitHub issues

File issues against origin upstream with gh. Read companions as needed:

• github_commands.md — list/link/verify recipes
• templates.md — body sections and title prefixes

Shared rules

1. Use upstream origin (not a fork-only default). Pass --repo owner/name when needed.
2. Run gh label list for that repo. Only use label names that exist. Never invent labels.
3. No promotional footers (“Made with Cursor”, etc.).
4. Hierarchy depth is only: Epic → Feature → Issue. Never nest under a leaf issue. Never Feature → Feature. Never deeper than three levels.
5. When parented: put Part of #<number>. at the top of the body, create the issue, then link with GraphQL addSubIssue. Body text alone is not enough. Verify parent afterward.
6. Do not use unsupported gh issue edit --set-parent.

Detect intent

User intent	Branch
Epic / large workstream	Create epic
Feature, design, refactor, perf, security, docs, test, chore, question	Create feature-family
Bug / unexpected behavior	Create bug
Leaf task under an existing feature	Create leaf under feature

If unclear, ask once which kind they want.

Hierarchy placement

Find epics

List open epics (type: epic and titles with [Epic] / [EPIC]). See github_commands.md.

Find features under an epic

List sub-issues of the candidate epic; prefer children whose titles start with [Feature] (or other feature-family prefixes) when attaching a leaf.

Match rules

• 0 matches: Tell the user none fit. Ask them to name an existing parent or create one first. Do not invent a parent.
• 1 clear match: Confirm number + title, then proceed.
• 2+ matches: Present #N — title with one-line why each might fit. Do not pick for the user.

Create epic

1. No parent search.
2. Title: [Epic] … (or [Epic]: … if matching existing style in the repo).
3. Labels: include type: epic plus other applicable existing labels.
4. Prefer REST create with type=Epic (see companion).
5. Body: summary of the workstream and what child features will cover. Use feature-request sections where useful (templates.md).

Create feature-family

Non-bug work that is not itself an epic ([Feature], [Design], [Refactor], [Performance], [Security], [Docs], [Test], [Chore], [Question], …).

1. Parent Epic is required. Do not create with no parent.
2. Confirm epic via placement rules above.
3. Labels: always --label needs-triage plus other applicable existing labels (e.g. enhancement).
4. Title prefix from the table in templates.md.
5. Body sections from feature_request.yml (templates.md).
6. Create, addSubIssue under the epic, verify.

Create leaf under feature

Use when the user wants a sub-issue of an existing feature (bug/chore/task scoped to that feature).

1. Resolve parent Feature (must already be under an Epic — depth stays ≤ 3).
2. If the feature has no epic parent, stop and fix hierarchy with the user before filing.
3. Body/labels/title per bug or feature-family templates as appropriate.
4. Create, addSubIssue under the Feature, verify.

Create bug

1. Labels: --label bug plus other applicable existing labels (template also uses needs-triage when present in the repo).
2. Title prefix: [Bug]: …
3. Body sections from bug_report.yml (templates.md).
4. Placement:
   • Small self-contained bug (narrow repro, no design change, not part of a larger workstream): may proceed without a parent. Say so explicitly when filing.
   • Otherwise: search for a fitting Feature under an Epic, then for a fitting Epic.
   • If a Feature fits: confirm, parent under that Feature.
   • If no Feature fits (non-trivial bug): ask the user to choose:
     1. Attach under an existing or new Feature (under an Epic)
     2. Attach directly under an Epic (depth 2)
     3. File with no parent (state that in the issue)
   • Do not invent a Feature. Do not auto-pick among 2+ candidates.
5. Create, link if parented, verify.

Done checklist

• Correct upstream repo
• Labels exist in gh label list
• Hierarchy depth respected
• Template sections filled from user/context
• addSubIssue + parent verified when parented
• Issue URL returned to the user