Gh Issue Creation Full Repo And Batch Setup

---
name: gh-issue-creation-full-repo-and-batch-setup
description: Create multiple related GitHub issues safely by resolving full OWNER/REPO, checking duplicates and labels first, and verifying each created issue.
version: 1.0.0
author: Hermes Agent
license: MIT
---

# GitHub issue creation: full repo resolution + batch setup

Use when asked to add one or more issues to a GitHub repo, especially when the user gives only a short repo name and wants several related issues created quickly.

## Why this exists

Two practical gotchas came up in live use:
1. `gh ... --repo` requires the full `OWNER/REPO` form, not just the repo name.
2. For multi-issue requests, it is safer to draft structured body files, create the issues, then immediately verify titles, URLs, labels, and body content rather than assuming creation succeeded exactly as intended.

## Workflow

1. Resolve the repository identity first.
   - If the user gives only `repo-name`, run:
     - `gh repo view repo-name --json nameWithOwner,url,description`
   - Then use the returned `OWNER/REPO` string for all subsequent commands.

2. Check for likely duplicates before creating anything.
   - Search issue titles/bodies with key terms from the request.
   - Example:
     - `gh issue list --repo OWNER/REPO --state all --limit 100 --search 'keyword1 OR keyword2 OR keyword3'`

3. Inspect available labels.
   - Example:
     - `gh label list --repo OWNER/REPO --limit 200`
   - Reuse the closest existing labels instead of inventing new ones unless explicitly asked.

4. Draft each issue body in a separate temp markdown file.
   - Include:
     - objective
     - scope / questions to answer
     - deliverables
     - constraints / framing
   - This avoids shell quoting problems and makes edits easy.

5. Create the issues.
   - Example:
     - `gh issue create --repo OWNER/REPO --title '...' --body-file /tmp/file.md --label enhancement`

6. If one issue is the umbrella/meta issue, edit it after creation to link the child issue numbers.
   - This is often easier than guessing future issue numbers ahead of time.

7. If you need to post a follow-up comment linking the newly created issues back to a parent/umbrella issue, resolve the issue numbers first and only then write/post the comment body.
   - Safe pattern:
     1. create the issues and capture their numeric IDs
     2. write the comment/body file with the real issue numbers already substituted
     3. post with `--body-file`
   - Do not leave literal placeholders like `#${NEW_NUM}` in the file you send to `gh issue comment`.
   - If a placeholder leaks into a posted comment, immediately add a correction comment with the real issue numbers.

7. Verify every created issue immediately.
   - Use:
     - `gh issue view N --repo OWNER/REPO --json number,title,url,labels,body`
   - Confirm:
     - title matches intent
     - correct labels applied
     - body rendered correctly
     - URLs/issue numbers recorded

8. When posting follow-up comments that mention newly created issue numbers, render placeholders before posting.
   - Do NOT leave shell placeholders like `#${NEW_NUM}` inside a heredoc/body file and assume later interpolation will happen automatically.
   - Safe pattern:
     - create the new issue
     - capture the numeric id
     - write the final body file with the concrete number already substituted
     - then post with `gh issue comment --body-file ...`
   - If a placeholder accidentally lands in a comment, immediately post a correction comment with the exact issue numbers.

## Scope / authorization guard fallback

If live `gh issue create` is blocked by a repo-specific guard, missing active scope, or authorization precondition, do not bypass it and do not stop with only prose. Prepare a durable issue packet instead:

1. write one Markdown file containing all issue bodies;
2. write a verified creation script that performs duplicate checks, creates issues, links umbrella/children, and verifies created issue metadata;
3. run `bash -n` on the script;
4. document the exact unblock step and command to run once scope is active;
5. report that live creation is blocked, not completed.

This preserves momentum while respecting repo gates.

## Critical gotcha


`gh --repo` does NOT accept a bare repo name.

Incorrect:
```bash
gh issue list --repo achantas-data
```

Typical failure:
```text
expected the "[HOST/]OWNER/REPO" format
```

Correct:
```bash
gh issue list --repo vamseeachanta/achantas-data
```

## Good fit

- user says "add issues to repo X"
- repo may not be cloned locally
- need to create multiple related research/planning issues
- want fast, low-risk GitHub issue setup with verification

## Verification checklist

- repo resolved to full `OWNER/REPO`
- duplicate search run
- labels inspected
- issue bodies stored in files
- all issue URLs captured
- umbrella issue updated with child references if applicable
- final `gh issue view` verification performed