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