managing-relationships

What this skill does

# 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:**
```bash
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue \
  --parent 67 \
  --child 68
```

**Remove Sub-Issue:**
```bash
python3 {baseDir}/scripts/manage-relationships.py remove-sub-issue \
  --parent 67 \
  --child 68
```

**List Sub-Issues:**
```bash
python3 {baseDir}/scripts/manage-relationships.py list-sub-issues --issue 67
```

### 2. **Dependency Management (Blocking)**

Track blocking dependencies between issues.

**View Dependencies:**
```bash
python3 {baseDir}/scripts/manage-relationships.py show-dependencies --issue 68
```

### 3. **Relationship Queries**

Query complex relationship graphs.

**Get Parent:**
```bash
python3 {baseDir}/scripts/manage-relationships.py get-parent --issue 68
```

**Get All Relationships:**
```bash
python3 {baseDir}/scripts/manage-relationships.py show-all --issue 67
```

## GraphQL API Reference

### Key Mutations

#### addSubIssue
Creates a parent-child relationship.

```graphql
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.

```graphql
mutation {
  removeSubIssue(input: {
    issueId: "PARENT_NODE_ID",
    subIssueId: "CHILD_NODE_ID"
  }) {
    issue { number }
    subIssue { number }
  }
}
```

#### reprioritizeSubIssue
Reorders sub-issues within a parent.

```graphql
mutation {
  reprioritizeSubIssue(input: {
    issueId: "PARENT_NODE_ID",
    subIssueId: "CHILD_NODE_ID",
    afterId: "SIBLING_NODE_ID"
  }) {
    issue { number }
  }
}
```

### Key Query Fields

#### Issue Relationships

```graphql
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

```bash
gh api graphql -f query='
query {
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 67) { id }
  }
}'
```

### Add Multiple Sub-Issues

```bash
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

```bash
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

```bash
# 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)
```

```bash
# 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

```bash
# 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

```bash
# 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 patte