Skip to content

Latest commit

 

History

History
86 lines (58 loc) · 3.75 KB

issue-arborist.md

File metadata and controls

86 lines (58 loc) · 3.75 KB

🌳 Issue Arborist

For an overview of all available workflows, see the main README.

Daily automated workflow that organizes your issue tracker by linking related issues as parent-child relationships

The Issue Arborist workflow keeps your issue tracker tidy and navigable. Every day it analyzes your open issues, detects natural parent-child relationships (epics with tasks, bugs with root causes, related feature clusters), and links them as GitHub sub-issues. When it finds five or more related issues with no common parent, it creates one.

Installation

# Install the 'gh aw' extension
gh extension install github/gh-aw

# Add the workflow to your repository
gh aw add-wizard githubnext/agentics/issue-arborist

This walks you through adding the workflow to your repository.

How It Works

graph LR
    A[Fetch 100 open issues] --> B[Analyze relationships]
    B --> C{Cluster of 5+?}
    C -->|Yes| D[Create parent issue]
    D --> E[Link sub-issues]
    C -->|No| F{Existing hierarchy?}
    F -->|Yes| E
    F -->|No| G[Noop: no action needed]
    E --> H[Done]
Loading

The workflow downloads the 100 most recent open issues (excluding those already linked as sub-issues), then applies semantic analysis to detect clusters and hierarchies. It only acts when it's confident — it's designed to be conservative and precise, creating links only when the relationship is clear.

What it links

Pattern Example
Feature with tasks "Add OAuth support" → "Implement OAuth login", "Add OAuth callback handler"
Epic with work items "[Epic] Refactor auth module" → related refactoring issues
Bug with root cause "Login fails on mobile" links to "Session cookie not set for mobile agents"
Orphan clusters 5+ issues all about "documentation" → new "[Parent] Documentation Improvements"

What it won't do

  • Link issues when the relationship is ambiguous or weak
  • Create parent issues for fewer than 5 related orphan issues
  • Re-process issues that already have a parent

Examples

From Peli's Agent Factory:

"The Issue Arborist has created 77 discussion reports and 18 parent issues to group related sub-issues. It keeps the issue tracker organized by automatically linking related issues, building a dependency tree we'd never maintain manually."

Example: grouping engine documentation updates into a single trackable parent (#12037).

Usage

Configuration

The workflow runs daily and can also be triggered manually from the Actions tab. It works out of the box with no configuration needed.

Limits per run:

  • Maximum 5 new parent issues created
  • Maximum 50 sub-issue links created

After editing the workflow file, run gh aw compile to update the compiled workflow and commit all changes to the default branch.

When to use it

Issue Arborist is most effective when:

  • Your repository has 20+ open issues
  • Issues are created organically (without always setting explicit parent-child relationships)
  • You want to surface hidden structure in your backlog

It complements Issue Triage (which labels and prioritizes issues) and Sub-Issue Closer (which closes parents when all sub-issues are done).

Learn More