Issue hierarchy and sub-issues

Issue hierarchy lets a Team break one Issue into smaller Issues. Every sub-issue is a normal Team-owned Issue with its own key, status, priority, assignee, Feature, labels, document, Activity, and lifecycle.

Hierarchy is intentionally separate from Issue relations and dependencies. A parent/sub-issue link describes work breakdown. Related, blocked-by, and blocking links describe coordination between otherwise independent Issues.

Hierarchy rules

• A parent and sub-issue must belong to the same Team.
• An Issue cannot be its own parent, and a parent change cannot create a cycle.
• Nesting can continue through multiple levels. Detail and table surfaces load bounded portions of the tree so large hierarchies remain responsive.
• A sub-issue can have only one direct parent. A parent can have many direct sub-issues.
• Moving an Issue to another Team preserves only hierarchy links that remain valid for the moved subtree.

Create a sub-issue

Open an Issue and use the Sub-issues section to add work beneath it. The inline form keeps the parent and Team fixed, then lets you set the new Issue's title and normal create properties.

The new sub-issue inherits the parent's priority and primary Feature by default. It inherits the assignee only when that person is still assignable in the Team. Labels are not inherited. You can change the available values before creating the sub-issue.

Create can stay open for repeated entry. Each successful row appears immediately in the parent's sub-issue list and receives its own Team-scoped key.

Set, change, or remove a parent

Use an Issue's actions to Set parent. The picker lists valid, readable Issues from the same Team and excludes choices that would create a cycle. Selecting a different parent moves the Issue to that parent.

From a Team Issue table, you can also right-click the Issue that should become the parent and choose Mark as → Parent of.... Search for the intended child, select it, and review the before-and-after hierarchy before confirming. If the selected Issue already has a parent, the confirmation explains that it will move; its existing descendants move with it, while its status, priority, assignee, Feature, labels, and other properties stay unchanged.

Use Remove parent to return an Issue to the top level.

These actions require the server-projected hierarchy capability for the Issue. Being able to open an Issue, knowing its key, or receiving a direct share does not grant permission to change hierarchy.

Apply hierarchy to a selection

Select editable active Issues from one Team and open Actions:

• Create related → Parent issue... creates one parent and moves every retained selected Issue beneath it. The create dialog shows every selection in the ordinary Sub-issues card, where you can review properties, remove individual rows, or add more draft children.
• Mark as → Sub-issue of... moves every selected Issue beneath one chosen parent.
• With exactly one selected Issue, Mark as → Parent of... makes it the parent of one chosen child.
• Remove relations → Remove parent detaches only selected Issues that currently have a parent. It never detaches all children from a selected parent.

Bulk Create related does not offer Sub-issue.... Create a child from an individual parent Issue when you need that direction.

While creating any non-Triage Issue, choose Add sub-issue from the ellipsis menu to open the child editor. Saving the first child switches to the Sub-issues overview card; use that card to add, edit, or remove more drafts. Each draft shows Pending in the Issue-key position until creation assigns its real Team Issue key. The main Issue is created first, then those retained drafts are created beneath it.

If one or more children cannot be confirmed, the parent remains created and only the unresolved drafts stay in the dialog with their attachments. Use Retry sub-issues to finish them without creating the parent again, or explicitly remove/cancel a draft to discard it.

The target and confirmation flow excludes cycle-forming choices and explains how many existing parent links will change. The full selection is preflighted and committed atomically. Parent removal review remains in the same selection palette and reports affected versus selected Issues. If cloned attachments exceed 25 children, 100 copies, or 1 GiB expanded bytes, select fewer parents or attachments.

Read hierarchy in detail and tables

The Issue detail page shows parent context and a Sub-issues section. Direct-child progress summarizes completed versus total visible children. Display controls can include additional properties for each visible child and can include completed sub-issues.

Team, My Issues, Feature, and Cycle Issue tables can show parent context and direct-child progress. Hierarchy filters let you focus on top-level Issues, sub-issues, or Issues with children. Local hierarchy display and filter drafts use the same table-control persistence as the rest of the Issue table.

Counts and progress are visibility-aware. A hidden child is not exposed through its title, key, properties, or a hidden-count side channel.

Privacy and direct sharing

Private Team access still controls the hierarchy. A direct share grants read access only to the shared Issue; it does not reveal hidden ancestors, descendants, or private Team option lists.

For a directly shared Issue, Integrity can show the Issue's own display-safe key, title, assignee, labels, and route. Private Team identity, Feature context, Cycle context, hidden hierarchy references, and hidden counts stay redacted. Direct-share-only access is read-only.

Delete and restore a hierarchy

When deleting a parent with active descendants, the confirmation explains the hierarchy impact. You can delete only the selected Issue, which detaches surviving children to the top level, or delete the selected hierarchy as one recoverable cascade when the action is available.

A cascade records one batch and root so restore can distinguish descendants deleted by that operation from Issues deleted independently. Restore can rebuild the eligible parent chain or restore an Issue at the top level. Integrity never revives an independently deleted Issue merely because an ancestor is restored.

Permanent deletion keeps only display-safe tombstone/reference behavior and cannot be undone. See Archive and delete Issues for the full lifecycle contract.

Activity and realtime

Creating a sub-issue, setting a parent, changing a parent, and removing a parent create typed Issue Activity. Parent references use stored display snapshots when safe and fall back to restricted or unavailable copy when the referenced Issue cannot be read.

Hierarchy writes use the existing private Team/Issue realtime channels and refresh the parent, child, ancestor context, progress, detail, and visible list caches affected by the change.