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 patter