Managing Relationships

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

1. 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

2. Dependency Management (Blocking)

Track blocking dependencies between issues.

View Dependencies:

python3 {baseDir}/scripts/manage-relationships.py show-dependencies --issue 68

3. 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:

1. Create all issues first
2. Get node IDs for parent and children
3. Add each child as sub-issue of parent
4. 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

1. Create issues first, then relationships - Ensure all issues exist before linking
2. Document relationships in body - Add "Part of #X" for visibility
3. Check for existing parents - Avoid orphaning issues
4. Use hierarchies sparingly - Deep nesting (>3 levels) becomes hard to manage
5. 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.