Managing Relationships Skill
You are an expert at managing GitHub issue relationships using the GraphQL API. This skill provides capabilities beyond the standard gh issue CLI, enabling proper parent-child hierarchies, dependency tracking, and issue linking.
When to Use This Skill
Auto-invoke this skill when the conversation involves:
-
Creating parent-child issue relationships (sub-issues)
-
Setting up issue hierarchies or epics
-
Managing blocking/blocked-by dependencies
-
Linking related issues
-
Querying issue relationship graphs
-
Keywords: "parent issue", "sub-issue", "child issue", "blocked by", "blocking", "depends on", "epic", "hierarchy"
Your Capabilities
- Sub-Issue Management (Parent-Child)
Create explicit parent-child relationships using GitHub's sub-issues feature.
Add Sub-Issue:
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue
--parent 67
--child 68
Remove Sub-Issue:
python3 {baseDir}/scripts/manage-relationships.py remove-sub-issue
--parent 67
--child 68
List Sub-Issues:
python3 {baseDir}/scripts/manage-relationships.py list-sub-issues --issue 67
- Dependency Management (Blocking)
Track blocking dependencies between issues.
View Dependencies:
python3 {baseDir}/scripts/manage-relationships.py show-dependencies --issue 68
- Relationship Queries
Query complex relationship graphs.
Get Parent:
python3 {baseDir}/scripts/manage-relationships.py get-parent --issue 68
Get All Relationships:
python3 {baseDir}/scripts/manage-relationships.py show-all --issue 67
GraphQL API Reference
Key Mutations
addSubIssue
Creates a parent-child relationship.
mutation { addSubIssue(input: { issueId: "PARENT_NODE_ID", subIssueId: "CHILD_NODE_ID" }) { issue { number title } subIssue { number title } } }
Input Fields:
-
issueId (required): Parent issue node ID
-
subIssueId : Child issue node ID
-
subIssueUrl : Alternative - child issue URL
-
replaceParent : Boolean to replace existing parent
removeSubIssue
Removes a parent-child relationship.
mutation { removeSubIssue(input: { issueId: "PARENT_NODE_ID", subIssueId: "CHILD_NODE_ID" }) { issue { number } subIssue { number } } }
reprioritizeSubIssue
Reorders sub-issues within a parent.
mutation { reprioritizeSubIssue(input: { issueId: "PARENT_NODE_ID", subIssueId: "CHILD_NODE_ID", afterId: "SIBLING_NODE_ID" }) { issue { number } } }
Key Query Fields
Issue Relationships
query { repository(owner: "OWNER", name: "REPO") { issue(number: 67) { # Parent-child parent { number title } subIssues(first: 50) { nodes { number title state } } subIssuesSummary { total completed percentCompleted }
# Dependencies
blockedBy(first: 10) {
nodes { number title }
}
blocking(first: 10) {
nodes { number title }
}
# Tracking (from task lists)
trackedInIssues(first: 10) {
nodes { number title }
}
trackedIssues(first: 10) {
nodes { number title }
}
trackedIssuesCount
}
} }
Direct GraphQL Usage
For operations not covered by scripts, use gh api graphql directly:
Get Issue Node IDs
gh api graphql -f query=' query { repository(owner: "OWNER", name: "REPO") { issue(number: 67) { id } } }'
Add Multiple Sub-Issues
gh api graphql -f query=' mutation { add1: addSubIssue(input: {issueId: "PARENT_ID", subIssueId: "CHILD1_ID"}) { subIssue { number } } add2: addSubIssue(input: {issueId: "PARENT_ID", subIssueId: "CHILD2_ID"}) { subIssue { number } } }'
Query Full Hierarchy
gh api graphql -f query=' query { repository(owner: "OWNER", name: "REPO") { issue(number: 67) { number title subIssues(first: 100) { nodes { number title state subIssues(first: 10) { nodes { number title } } } } } } }'
Workflow Patterns
Pattern 1: Create Issue Hierarchy
When creating a parent issue with children:
-
Create all issues first
-
Get node IDs for parent and children
-
Add each child as sub-issue of parent
-
Verify relationships
Step 1: Get IDs
python3 {baseDir}/scripts/manage-relationships.py get-ids --issues 67,68,69,70
Step 2: Add relationships
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 68 python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 69 python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 70
Step 3: Verify
python3 {baseDir}/scripts/manage-relationships.py list-sub-issues --issue 67
Pattern 2: Epic with Nested Sub-Issues
For complex hierarchies:
Epic (#1) ├── Feature A (#2) │ ├── Task A1 (#5) │ └── Task A2 (#6) └── Feature B (#3) └── Task B1 (#7)
Top-level children
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 1 --child 2 python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 1 --child 3
Nested children
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 2 --child 5 python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 2 --child 6 python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 3 --child 7
Pattern 3: Move Issue to New Parent
Use replaceParent flag
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue
--parent 100
--child 68
--replace-parent
Error Handling
Common Errors
"Issue may not contain duplicate sub-issues"
-
Child is already a sub-issue of this parent
-
Check existing relationships first
"Sub issue may only have one parent"
-
Child already has a different parent
-
Use --replace-parent flag or remove from current parent first
"Issue not found"
-
Verify issue numbers exist
-
Check repository owner/name
Troubleshooting
Check if issue has parent
python3 {baseDir}/scripts/manage-relationships.py get-parent --issue 68
List all relationships
python3 {baseDir}/scripts/manage-relationships.py show-all --issue 68
Integration with Other Skills
With creating-issues skill
-
After creating issues, use this skill to establish relationships
-
Reference parent in issue body: "Part of #67"
With organizing-with-labels skill
-
Labels indicate type, relationships indicate structure
-
Use together for complete issue organization
With managing-projects skill
-
Sub-issues appear in project boards
-
Track hierarchy progress in projects
Environment Requirements
This skill requires:
-
gh CLI authenticated with appropriate permissions
-
Repository with Issues enabled
-
GraphQL API access
Best Practices
-
Create issues first, then relationships - Ensure all issues exist before linking
-
Document relationships in body - Add "Part of #X" for visibility
-
Check for existing parents - Avoid orphaning issues
-
Use hierarchies sparingly - Deep nesting (>3 levels) becomes hard to manage
-
Combine with labels - Use type:epic label for parent issues
Limitations
-
One parent per issue - Cannot have multiple parents
-
No circular references - A cannot be parent of B if B is ancestor of A
-
API rate limits - Batch operations carefully
-
Blocking relationships - Currently read-only via API (manage in UI)
Resources
Scripts
- manage-relationships.py: Main CLI for relationship operations
References
-
graphql-schema.md: Full GraphQL schema documentation
-
relationship-patterns.md: Common hierarchy patterns
Common Mistakes
Mistake 1: Using Task Lists Instead of Sub-Issues API
❌ WRONG - Task lists create "tracked" relationships, not parent-child:
Child Issues
- #68
- #69
- #70
✅ CORRECT - Use GraphQL addSubIssue mutation: python manage-relationships.py add-sub-issue --parent 67 --child 68 python manage-relationships.py add-sub-issue --parent 67 --child 69 python manage-relationships.py add-sub-issue --parent 67 --child 70
Why it matters:
-
Task lists only create "tracked by" links visible in the issue sidebar
-
Sub-issues create true parent-child hierarchy with:
-
Progress tracking (3/4 completed, 75%)
-
Hierarchical navigation in GitHub UI
-
Sub-issue aggregation and rollup
Mistake 2: Not Getting Issue Node IDs First
❌ WRONG - Using issue numbers directly in GraphQL: mutation { addSubIssue(input: {issueId: "67", subIssueId: "68"}) { ... } }
✅ CORRECT - Get node IDs first, then use them:
Step 1: Get node IDs
python manage-relationships.py get-ids --issues 67,68
Step 2: Use node IDs in mutation
mutation { addSubIssue(input: { issueId: "I_kwDOQTQw6c7Z4spt", subIssueId: "I_kwDOQTQw6c7Z4swL" }) { ... } }
Why it matters: GraphQL uses node IDs (not issue numbers). The script handles this automatically, but direct API calls require the conversion.
Mistake 3: Not Checking for Existing Parent
❌ WRONG - Adding sub-issue without checking existing parent: python manage-relationships.py add-sub-issue --parent 100 --child 68
Error: Sub issue may only have one parent
✅ CORRECT - Check first, then use --replace-parent if needed:
Check existing parent
python manage-relationships.py get-parent --issue 68
If has parent, use replace flag
python manage-relationships.py add-sub-issue --parent 100 --child 68 --replace-parent
Why it matters: Each issue can only have one parent. Attempting to add to a new parent without the replace flag will fail.
Mistake 4: Creating Circular References
❌ WRONG - Creating cycles in hierarchy:
A is parent of B
python manage-relationships.py add-sub-issue --parent A --child B
Then trying to make B parent of A
python manage-relationships.py add-sub-issue --parent B --child A
Error: Cannot create circular reference
✅ CORRECT - Plan hierarchy before creating: Epic (#1) ├── Feature A (#2) │ └── Task A1 (#5) └── Feature B (#3) └── Task B1 (#7)
Why it matters: GitHub prevents circular references. Plan your hierarchy structure before creating relationships.
Mistake 5: Not Verifying After Creation
❌ WRONG - Adding relationships without verification: python manage-relationships.py add-sub-issue --parent 67 --child 68
Just assume it worked
✅ CORRECT - Verify relationships were created: python manage-relationships.py add-sub-issue --parent 67 --child 68 python manage-relationships.py list-sub-issues --issue 67
Confirms: Sub-issues (4): #68, #69, #70, #71
Why it matters: API calls can fail silently or partially. Always verify the result matches expectations.
Mistake 6: Deep Nesting (>3 Levels)
❌ WRONG - Too many levels of nesting: Epic └── Theme └── Feature └── Story └── Task └── Subtask (6 levels!)
✅ CORRECT - Keep hierarchy shallow (2-3 levels): Epic ├── Feature A │ ├── Task A1 │ └── Task A2 └── Feature B └── Task B1
Why it matters: Deep nesting becomes hard to manage and navigate. Most projects work well with 2-3 levels maximum.
Important Notes
-
The standard gh issue CLI does NOT support relationship management
-
Always use GraphQL API via gh api graphql for relationships
-
Sub-issues appear in GitHub UI with progress tracking
-
Task list checkboxes (- [ ] #68 ) create "tracked" relationships, not parent-child
-
Each issue can have only ONE parent (no multiple inheritance)
-
Verify relationships after creation to confirm success