GitHub Issue Creation

Create GitHub Issues in two modes: standalone (interactive) or USDM (batch from requirements document). Works in any Git repository with GitHub as the remote.

Prerequisites

Before creating issues, verify the environment:

The current directory is a Git repository. If not, inform the user and stop.
The GitHub CLI (gh) is authenticated. If not, instruct the user to run gh auth login.

Mode 1: Standalone Issue

Create a single issue through dialogue with the user.

Step 1: Collect Details

Ask the user for an issue title (required).
Accept an optional issue body describing the issue in detail.
Accept optional labels for the issue.

If the user provides all details upfront (e.g., "create an issue titled X about Y"), skip the interactive prompts and proceed to creation.

Step 2: Create Issue

Create the issue immediately after collecting details:

gh issue create --title "<title>" --label "<labels>" --body "<body>"

Display the created issue number and URL.

Error Handling

If issue creation fails, display the error message returned by gh issue create.

Mode 2: USDM Document Input

Create a hierarchy of issues from a USDM requirements document. This mode is triggered when the user provides a USDM document path and a parent issue number.

Input

USDM document path: Path to a Markdown file following USDM format (REQ/SPEC hierarchy).
Parent issue number: The GitHub Issue under which top-level requirements are created as sub-issues.

Step 1: Parse Requirements

Read the USDM document.
Extract all requirements (both top-level REQ-NNN and sub-requirements REQ-NNN-N).
For each requirement, collect:
- ID and title
- Reason
- Description
- Child specifications (SPEC) belonging to that requirement
- Parent requirement (if it is a sub-requirement)
Display a summary of the extraction: total number of requirements and the list of REQ IDs. Proceed to creation unless the user explicitly aborts.

Step 2: Create Issues Top-Down

Process the hierarchy top-down (parents before children) because gh sub-issue add requires the parent issue number.

For each requirement:

Create a GitHub Issue with label usdm:req.
The issue title follows the convention: REQ-NNN: Title or REQ-NNN-N: Title.
The issue body uses this template:

## Reason

{Reason text from USDM document}

## Description

{Description text from USDM document}

## Specifications

| SPEC ID | Specification |
|---------|--------------|
| SPEC-NNN | {Specification text} |

## Source

- Document: [{document-id}]({link-to-document}) § {REQ-ID}
- Ticket: #{parent-issue-number}

Link the issue as a sub-issue:
- Top-level REQs become sub-issues of the parent issue.
- Sub-requirements become sub-issues of their parent requirement's issue.

gh issue create --title "REQ-001: Title" --label "usdm:req" --body "..."
gh sub-issue add <parent-issue-number> <new-issue-number>

Display the created issue number and URL after each creation.

Step 3: Verify Hierarchy

After all issues are created, verify the hierarchy with gh sub-issue list on the parent issue and report the result to the user.

Important Rules

Do not create separate issues for specifications (SPEC). Specifications are included in the parent requirement's issue body as a table.
Create usdm:req label if it does not exist: gh label create "usdm:req" --color 0075ca --description "USDM Requirement"
Each issue is self-contained: readable and understandable on its own, with a source reference link back to the USDM document.
Process top-down: always create parent issues before children.

See references/usdm-issue-mapping.md for the full mapping guide.

Before Finishing

After creating issues, review each one from a reader's perspective:

Self-contained? Can someone understand this issue without access to the conversation or source document? If the issue body lacks context (reason, scope, acceptance criteria), add it before moving on.
Source traceable? Does every issue link back to its origin (USDM document, idea document, or conversation context)? A reader should be able to find the full context if they need it.

Constraints

Do not create issues outside the current repository.
Do not modify existing issues unless explicitly part of the USDM hierarchy creation.
In USDM mode, display the count and REQ IDs before batch creation. Proceed unless the user aborts.