Splice Issue — Break Parent Issues into Sub-Issues

Break a parent issue into self-contained, independently mergeable sub-issues on GitHub.

Parse the issue number from $ARGUMENTS (accepts #123, 123, or a full GitHub URL).

Before You Start

Review existing spliced issues for structure patterns:

gh api graphql -f query='{ repository(owner: "bbvch-ai", name: "aihub-core") { issue(number: 919) { subIssues(first: 15) { nodes { number title state } } } } }'

Step 1: Fetch the Parent Issue

gh issue view $ISSUE_NUMBER -R bbvch-ai/aihub-core --json title,body,labels,milestone,assignees
PARENT_TYPE=$(gh api "repos/bbvch-ai/aihub-core/issues/$ISSUE_NUMBER" --jq '.type.name // empty')

Also fetch any existing sub-issues — the user may have started splicing already:

gh api graphql -F number=$ISSUE_NUMBER -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") {
      issue(number: $number) { id subIssues(first: 50) { nodes { number title state } } }
    }
  }'

Also fetch discussion comments for additional context and decisions:

gh issue view $ISSUE_NUMBER -R bbvch-ai/aihub-core --json comments --jq '.comments[].body'

Step 2: Analyze and Propose the Breakdown

Identify logical, self-contained units of work from the issue body. Each sub-issue must be:

• Independently mergeable: Can be implemented and merged on its own
• Self-contained: Has clear acceptance criteria that don't require other sub-issues to validate
• Appropriately scoped: Small enough to be a single PR, large enough to be meaningful

Present the proposed breakdown to the user BEFORE creating any issues. Include:

• Title for each sub-issue
• Draft acceptance criteria
• Dependency relationships (which issues block which)
• What gets removed from the parent issue

Wait for user confirmation before proceeding.

Step 3: Create Sub-Issues

For each approved sub-issue, create it with matching metadata from the parent:

gh issue create -R bbvch-ai/aihub-core \
  --title "Sub-issue title" \
  --body "$(cat <<'EOF'
Parent: #$ISSUE_NUMBER

Acceptance Criteria:

- [ ] Criterion 1
- [ ] Criterion 2
EOF
)" \
  --label "$PARENT_LABEL" \
  --milestone "$PARENT_MILESTONE" \
  --assignee "$PARENT_ASSIGNEE"

# Set the native issue type over REST, as write-issue does; older gh has no --type flag
# ($CHILD_NUMBER is the trailing number of the URL gh issue create printed)
gh api -X PATCH "repos/bbvch-ai/aihub-core/issues/$CHILD_NUMBER" -f type="$CHILD_TYPE"

Metadata inheritance rules:

• Copy --label (the area:* labels; never a major/minor/patch version label, those belong on PRs) from parent
• Copy --milestone from parent
• Copy --assignee from parent
• Set $CHILD_TYPE to $PARENT_TYPE, except under an Epic, where each child is a Feature or Task
• Body starts with Parent: #$ISSUE_NUMBER

Acceptance criteria rules:

• AC describes what should work, not how it's implemented
• No endpoint paths, class names, specific validation mechanisms, or other implementation details that could change
• Use behavior-oriented language ("users can switch tenants") not implementation-specific language ("composable exists for managing selected tenant with localStorage persistence")
• Implementation details belong in a separate "Implementation Proposal" section in the body

Step 4: Link as Sub-Issues

Get the parent issue node ID and each child's node ID, then link them:

PARENT_ID=$(gh api graphql -F number=$ISSUE_NUMBER -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") { issue(number: $number) { id } }
  }' -q '.data.repository.issue.id')

CHILD_ID=$(gh api graphql -F number=$CHILD_NUMBER -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") { issue(number: $number) { id } }
  }' -q '.data.repository.issue.id')

gh api graphql -f query="mutation { addSubIssue(input: { issueId: \"$PARENT_ID\", subIssueId: \"$CHILD_ID\" }) { issue { id } } }"

Step 5: Inherit Relationships from Parent

The parent's blocked-by and blocking relationships must transfer to the children. Fetch both:

gh api graphql -F number=$ISSUE_NUMBER -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") {
      issue(number: $number) {
        blockedBy(first: 10) { nodes { number id } }
        blocking(first: 10) { nodes { number id } }
      }
    }
  }'

• blocked-by: If parent is blocked by X, each child must also be blocked by X (the children can't start until X is done).
• blocking: If Y is blocked by parent, Y must now be blocked by each child (Y can't start until all children are done).

Apply the no-redundancy rule: skip if already covered transitively.

Step 6: Set Blocked-By Dependencies Between Children

For children that depend on each other, use the addBlockedBy mutation:

ISSUE_ID=$(gh api graphql -F number=$BLOCKED_ISSUE -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") { issue(number: $number) { id } }
  }' -q '.data.repository.issue.id')

BLOCKING_ID=$(gh api graphql -F number=$BLOCKING_ISSUE -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") { issue(number: $number) { id } }
  }' -q '.data.repository.issue.id')

gh api graphql -f query="mutation { addBlockedBy(input: { issueId: \"$ISSUE_ID\", blockingIssueId: \"$BLOCKING_ID\" }) { issue { id } } }"

Do NOT use addSubIssue for dependency relationships. Sub-issue = part of the work. Blocked-by = must be done first.

No redundant blocked-by relationships. Before adding a blocked-by link, check the existing blocked-by chain. If the blocking issue is already reachable transitively (e.g., A blocked by B, B blocked by C — don't also add A blocked by C), skip it. Check with:

gh api graphql -F number=$ISSUE_NUMBER -f query='
  query($number: Int!) {
    repository(owner: "bbvch-ai", name: "aihub-core") {
      issue(number: $number) {
        blockedBy(first: 10) {
          nodes { number title blockedBy(first: 10) { nodes { number title } } }
        }
      }
    }
  }'

Step 7: Copy Project Board Priorities to Children

Fetch the parent's project board field values (Priority, etc.) and copy them to each child issue. The parent may be on multiple project boards — copy priorities from all of them.

# Get parent's project items with priority values
gh api graphql -f query='
{
  node(id: "PARENT_NODE_ID") {
    ... on Issue {
      projectItems(first: 10) {
        nodes {
          id
          project { number title id }
          fieldValues(first: 20) {
            nodes {
              ... on ProjectV2ItemFieldSingleSelectValue {
                field { ... on ProjectV2SingleSelectField { name id } }
                name
                optionId
              }
            }
          }
        }
      }
    }
  }
}'

# For each child, get its project item IDs and set the same Priority values
gh api graphql -f query="
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: \"PROJECT_ID\"
    itemId: \"CHILD_ITEM_ID\"
    fieldId: \"PRIORITY_FIELD_ID\"
    value: { singleSelectOptionId: \"PRIORITY_OPTION_ID\" }
  }) { projectV2Item { id } }
}"

Step 8: Clean Up the Parent Issue

After all sub-issues are created and linked:

1. Remove acceptance criteria from the parent issue body. AC lives only on leaf issues (issues with no children).
2. Keep context sections (background, design decisions, discussion history) — these provide valuable context for anyone working on the sub-issues.
3. Do NOT create separate documentation sub-issues. Documentation is part of the Definition of Done for every issue.

Step 9: Present Summary

Show the user the final structure with dependency graph:

#919 Parent Issue (no AC, context only)
├── #954 Foundational issue (no deps)
│   ↓ blocks
├── #956 Mid-layer issue
│   ↓ blocks
├── #955 Leaf issue (blocked by #956)
└── #963 Leaf issue (blocked by #956)

Wait for the user to explicitly confirm that all sub-issues are correct and complete before proceeding. Do NOT close the parent until the user says they are happy with the breakdown.

Step 10: Close the Parent Issue

Only after the user has confirmed all sub-issues are correct, close the parent issue. The work now lives in the children — the parent is just a container.

gh issue close $ISSUE_NUMBER -R bbvch-ai/aihub-core -r "not planned" -c "Spliced into sub-issues. Work continues in child issues."

Common Mistakes

1. Creating documentation as a separate sub-issue. Documentation is DoD for every issue — never split it out.
2. Leaving acceptance criteria on the parent issue. Once a parent has sub-issues, remove its AC. The parent is done when all children are done.
3. Using addSubIssue for dependencies. Sub-issue means "part of this work." Use addBlockedBy for "must be done before."
4. Forgetting to inherit metadata. Every sub-issue must have the same area:* labels, milestone, and assignee as the parent, plus the parent's native issue type (children of an Epic are Features or Tasks).
5. Creating issues before getting user confirmation. Always present the proposed breakdown and wait for approval.
6. Adding redundant blocked-by relationships. If A is blocked by B, and B is blocked by C, do NOT also add A blocked by C. Check the transitive chain first.
7. Not copying project board priorities. Every sub-issue must inherit the parent's Priority field values from all project boards.
8. Putting implementation details in acceptance criteria. AC describes behavior, not implementation. Put implementation details in a separate "Implementation Proposal" section.
9. Not inheriting blocked-by/blocking relationships. Children must inherit the parent's blocked-by (prerequisites) and blocking (dependents) relationships. Otherwise the dependency graph breaks when the parent is closed.