Managing GitHub Sub-issues

Purpose

Provides a standardized way to manage hierarchical relationships between issues using the GitHub Sub-issues REST API. Since sub-issues are not yet first-class flags in the gh issue commands, this skill uses gh api for direct interaction.

1. Safety & Verification

Before executing any commands, the agent must:

1. Context Verification: Ensure gh-verifying-context has been run and confirmed.
2. Human-in-the-Loop: Preview all state-changing commands (POST, DELETE, PATCH) to the user for approval.
3. Repository Confirmation: Ensure you are targeting the correct repository and issue numbers.

2. Common Workflows

Workflow: List Sub-issues

Lists all sub-issues associated with a specific parent issue.

Command:

gh api /repos/{owner}/{repo}/issues/{issue_number}/sub_issues

Workflow: Add Sub-issue

Links an existing issue as a sub-issue to a parent issue.

Command:

gh api --method POST /repos/{owner}/{repo}/issues/{parent_number}/sub_issues \
  -F sub_issue_id={sub_issue_id}

Note: sub_issue_id is the database ID of the issue, not the issue number. You can find this in the output of gh issue view or by querying the API.

Workflow: Remove Sub-issue

Unlinks a sub-issue from its parent issue.

Command:

gh api --method DELETE /repos/{owner}/{repo}/issues/{parent_number}/sub_issue \
  -F sub_issue_id={sub_issue_id}

Workflow: Reprioritize Sub-issue

Changes the order of a sub-issue within its parent's list.

Command:

# Move sub-issue after another sub-issue
gh api --method PATCH /repos/{owner}/{repo}/issues/{parent_number}/sub_issues/priority \
  -F sub_issue_id={sub_issue_id} \
  -F after_id={after_id}

# Move sub-issue before another sub-issue
gh api --method PATCH /repos/{owner}/{repo}/issues/{parent_number}/sub_issues/priority \
  -F sub_issue_id={sub_issue_id} \
  -F before_id={before_id}

3. Error Handling

• Invalid ID: If the API returns a 404 or validation error, double-check that you are using the id (integer) and not the number.
• Permissions: Ensure the token has write access to the repository for state-changing operations.
• Limit Exceeded: GitHub currently allows up to 100 sub-issues per parent and up to 8 levels of nesting.