How to Break Down Work with Sub-Issues in GitHub
Teams tracking work in GitHub used to break down features with task lists in the issue body, which were easy to create and hard to report on. Sub-issues give that hierarchy a proper structure: a parent issue with child issues, each with its own assignee, labels, and status, and a progress indicator on the parent.
This guide covers when to use sub-issues, how to create and organize them, how to use the hierarchy in GitHub Projects, and conventions that keep breakdowns useful. It is aimed at PMs and engineering leads who plan in GitHub Issues and Projects.
Working in GitHub? Turn your spec into dependency-ordered tickets.
Paste the feature or spec. Vantage pulls out the requirements and breaks them into tickets, ordered by what blocks what, ready to groom with your team.
How this works
- We save what you typed. No AI runs on this page.
- You create a free account.
- Vantage builds a PRD and dependency-ordered tickets from it inside your own workspace.
Why ask for an account? We’re a small team, and a full generation runs a multi-step AI pipeline that costs us real money. So we tie it to a free account instead of running it anonymously. You also get to keep the result and edit it.
Your text is only used to create your project, and it stays private to your account. If you don’t sign up, we delete it after 7 days. Privacy policy
Step-by-step guide
Decide what a parent issue represents
Agree on what level of work gets a parent issue. A common pattern is parent issues for features or epics, and sub-issues for pieces of work that one person can finish in a few days. If your organization uses issue types, a parent might be a Feature and its children Tasks or Bugs.
- Define what a parent issue represents in your team
- Define the target size for sub-issues
- Decide whether nesting beyond one level is allowed
Create sub-issues from the parent
Open the parent issue and use the sub-issues section to create a new sub-issue or add an existing one. New sub-issues can be created in the same repository or, where permitted, another repository in the organization. Each sub-issue is a full issue with its own assignee, labels, and milestone.
- Open the parent issue
- Create new sub-issues or add existing issues as sub-issues
- Assign owners and labels to each sub-issue
- Reorder sub-issues to reflect sequence
Write a clear parent description
The parent issue should describe the goal, scope, and acceptance criteria for the whole feature, plus a link to the spec. Sub-issues should each describe one piece of the work. This separation keeps the parent useful as the place stakeholders check for status.
Track progress on the parent
The parent issue shows how many sub-issues are completed. Use this as a quick status check. If progress stalls, open the sub-issues to see which are blocked or unassigned.
Use the hierarchy in GitHub Projects
GitHub Projects can display parent issue and sub-issue progress fields. Add them to a table view to see each feature with its progress, or group by parent issue to see all the work for a feature together. This gives PMs a feature-level roadmap view built from the same issues engineers work on.
- Add the parent issue field to your project
- Add the sub-issue progress field to table views
- Create a view grouped by parent issue
- Filter to open parents for a feature-level status view
Model dependencies explicitly
Sub-issues show hierarchy, not order. If one sub-issue must be done before another, note it in the description or use your team's convention for blocking relationships. Hierarchy and dependency are different questions, and mixing them causes confusion in planning.
Close the parent deliberately
Do not close the parent automatically when the last sub-issue closes unless that matches your process. Often a feature still needs QA, documentation, or a launch step. Close the parent when the outcome described in it is achieved.
Common mistakes
Nesting too deep
Three or four levels of nesting makes it hard to find work. GitHub limits nesting depth, and most teams need only one or two levels.
Sub-issues that are too large
If a sub-issue takes two weeks, it hides progress the same way a large parent would. Split it further.
Using hierarchy for sequence
Ordering sub-issues does not create dependencies. Document blocking relationships separately.
Tips
Link the PRD or spec in every parent issue description.
Use a consistent title prefix on parent issues so they are easy to find in search.
Review parent issues with low progress in weekly planning.
Keep acceptance criteria on the parent and implementation details on sub-issues.
How Vantage helps
Breaking a feature into sub-issues is where requirements often lose their shape. Vantage generates tickets from PRD requirements with dependencies mapped and work grouped into waves, and lets PMs query the GitHub codebase while scoping, so the breakdown reflects both the spec and the system before tickets are pushed to the tracker.