diff --git a/README.md b/README.md index a070bf1..f563e68 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,10 @@ A sample family of reusable [GitHub Agentic Workflows](https://github.github.com ## πŸ“‚ Available Workflows -### Triage Workflows +### Triage & Issue Management Workflows - [🏷️ Issue Triage](docs/issue-triage.md) - Triage issues and pull requests +- [πŸ”’ Sub-Issue Closer](docs/sub-issue-closer.md) - Automatically close parent issues when all sub-issues are completed ## Fault Analysis Workflows diff --git a/docs/sub-issue-closer.md b/docs/sub-issue-closer.md new file mode 100644 index 0000000..b9f0824 --- /dev/null +++ b/docs/sub-issue-closer.md @@ -0,0 +1,94 @@ +# Sub-Issue Closer + +**Automatically closes parent issues when all their sub-issues are completed** + +## Overview + +The Sub-Issue Closer is an automated workflow that maintains a clean and organized issue tracker by automatically closing parent issues when all of their sub-issues have been completed. It runs daily and processes the issue hierarchy recursively, ensuring that parent issues up the tree are also closed as their sub-issues complete. + +## How It Works + +1. **Scans for Parent Issues**: The workflow searches for open issues that have sub-issues (tracked issues) +2. **Checks Completion Status**: For each parent issue, it verifies that ALL sub-issues are closed +3. **Closes Completed Parents**: When a parent issue has 100% of its sub-issues closed, it automatically closes the parent +4. **Processes Recursively**: After closing a parent, it checks if that parent is itself a sub-issue of another parent, and repeats the process up the tree +5. **Adds Transparency**: Each closure includes an explanatory comment showing the sub-issue completion status + +## Why This Is Valuable + +- **Keeps Issue Tracker Clean**: Automatically closes parent issues that are implicitly complete +- **Saves Manual Work**: Eliminates the need to manually track and close parent issues +- **Provides Clarity**: Team members can see at a glance which initiatives are fully complete +- **Recursive Processing**: Handles nested issue hierarchies automatically +- **Conservative Approach**: Only closes when absolutely certain all sub-issues are done + +## When It Runs + +- **Daily**: Automatically runs once per day on a fuzzy schedule +- **On-Demand**: Can be manually triggered via workflow_dispatch + +## Example Scenario + +Imagine you have a parent issue tracking a new feature with 5 sub-issues: + +`````` +Issue #100: "Feature: Add User Profile" +β”œβ”€β”€ #101: "Design profile page" [CLOSED] +β”œβ”€β”€ #102: "Implement backend API" [CLOSED] +β”œβ”€β”€ #103: "Create frontend UI" [CLOSED] +β”œβ”€β”€ #104: "Write tests" [CLOSED] +└── #105: "Update documentation" [CLOSED] +`````` + +When the last sub-issue (#105) is closed, the next time Sub-Issue Closer runs, it will: +1. Detect that issue #100 has all 5 sub-issues closed (100%) +2. Automatically close issue #100 +3. Add a comment: "πŸŽ‰ Automatically closed by Sub-Issue Closer - All sub-issues completed (5/5)" +4. Check if #100 is itself a sub-issue of a higher-level parent and repeat + +## Configuration + +The workflow is configured with conservative limits: +- **Maximum 20 issues closed per run**: Prevents accidental mass closures +- **Maximum 20 comments added per run**: Respects API rate limits +- **Daily schedule**: Provides regular cleanup without overwhelming noise +- **Read-only GitHub permissions**: Cannot modify code, only issue status + +## Best Practices + +- **Use Sub-Issues**: Create parent issues with sub-issues to track multi-part work +- **Keep Sub-Issues Updated**: Close sub-issues promptly when completed +- **Trust the Automation**: The workflow is conservative and only closes when 100% certain +- **Review Closure Comments**: Each automated closure includes a transparent explanation + +## What Makes This Workflow Special + +- **Simple and Focused**: Does one thing well - closes completed parent issues +- **Language-Agnostic**: Works with any repository that uses GitHub Issues +- **Zero Configuration**: Works out-of-the-box with standard GitHub issue tracking +- **Recursive Logic**: Handles complex nested issue hierarchies automatically +- **Transparent Operation**: Every action is logged and explained in comments + +## Merge Rate + +While this workflow doesn't create pull requests (it manages issues directly), its sister workflow in the gh-aw repository has been deployed successfully and operates automatically without intervention, demonstrating its reliability and effectiveness in production use. + +## Adding to Your Repository + +``````bash +gh aw add workflows/sub-issue-closer.md +gh aw compile +`````` + +Then commit and push the compiled workflow to your repository. + +## Related Workflows + +- [Issue Triage](issue-triage.md) - Automatically labels and organizes new issues +- [Daily Plan](daily-plan.md) - Creates and updates planning issues with sub-tasks + +## Learn More + +- [GitHub Issues Documentation](https://docs.github.com/en/issues) +- [Sub-Issues and Task Lists](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-task-lists) +- [GitHub Agentic Workflows](https://github.github.io/gh-aw/) diff --git a/workflows/sub-issue-closer.md b/workflows/sub-issue-closer.md new file mode 100644 index 0000000..01f6d66 --- /dev/null +++ b/workflows/sub-issue-closer.md @@ -0,0 +1,150 @@ +--- +description: Scheduled workflow that recursively closes parent issues when all sub-issues are 100% complete +name: Sub-Issue Closer +on: + schedule: daily + workflow_dispatch: +permissions: + contents: read + issues: read +engine: copilot +strict: true +network: + allowed: + - defaults +tools: + github: + toolsets: + - issues +safe-outputs: + update-issue: + status: + target: "*" + max: 20 + add-comment: + target: "*" + max: 20 +timeout-minutes: 15 +--- + +# Sub-Issue Closer πŸ”’ + +You are an intelligent agent that automatically closes parent issues when all their sub-issues are 100% complete. + +## Task + +Recursively process GitHub issues in repository **${{ github.repository }}** and close parent issues that have all their sub-issues completed. + +## Process + +### Step 1: Find Open Parent Issues + +Use the GitHub MCP server to search for open issues that have sub-issues. Look for: +- Issues with state = "OPEN" +- Issues that have tracked issues (sub-issues) +- Issues that appear to be tracking/parent issues based on their structure + +You can use the `search_issues` tool to find issues with sub-issues, or use `list_issues` to get all open issues and filter those with sub-issues. + +### Step 2: Check Sub-Issue Completion + +For each parent issue found, check the completion status of its sub-issues: + +1. Get the sub-issues for the parent issue using the GitHub API +2. Check if ALL sub-issues are in state "CLOSED" +3. Calculate the completion percentage + +**Completion Criteria:** +- A parent issue is considered "100% complete" when ALL of its sub-issues are closed +- If even one sub-issue is still open, the parent should remain open +- Empty parent issues (no sub-issues) should be skipped + +### Step 3: Recursive Processing + +After closing a parent issue: +1. Check if that issue itself is a sub-issue of another parent +2. If it has a parent issue, check that parent's completion status +3. Recursively close parent issues up the tree as they reach 100% completion + +**Important:** Process the tree bottom-up to ensure sub-issues are evaluated before their parents. + +### Step 4: Close Completed Parent Issues + +For each parent issue that is 100% complete: + +1. **Close the issue** using the `update_issue` safe output: + ``````json + {"type": "update_issue", "issue_number": 123, "state": "closed", "state_reason": "completed"} + `````` + +2. **Add a comment** explaining the closure using the `add_comment` safe output: + ``````json + {"type": "add_comment", "issue_number": 123, "body": "πŸŽ‰ **Automatically closed by Sub-Issue Closer**\n\nAll sub-issues have been completed. This parent issue is now closed automatically.\n\n**Sub-issues status:** X/X closed (100%)"} + `````` + +### Step 5: Report Summary + +At the end of processing, provide a summary of: +- Total parent issues analyzed +- Issues closed in this run +- Issues that remain open (with reason: incomplete sub-issues) +- Any errors or issues that couldn't be processed + +## Constraints + +- Maximum 20 issues closed per run (configured in safe-outputs) +- Maximum 20 comments added per run +- Only close issues when you are ABSOLUTELY certain all sub-issues are closed +- Skip issues that don't have sub-issues +- Only process open parent issues +- Be conservative: when in doubt, don't close + +## Example Output Format + +During processing, maintain clear logging: + +`````` +πŸ” Analyzing parent issues... + +πŸ“‹ Issue #42: "Feature: Add dark mode" + State: OPEN + Sub-issues: 5 total + - #43: "Design dark mode colors" [CLOSED] + - #44: "Implement dark mode toggle" [CLOSED] + - #45: "Add dark mode to settings" [CLOSED] + - #46: "Test dark mode" [CLOSED] + - #47: "Document dark mode" [CLOSED] + Status: 5/5 closed (100%) + βœ… All sub-issues complete - CLOSING + +πŸ“‹ Issue #50: "Feature: User authentication" + State: OPEN + Sub-issues: 3 total + - #51: "Add login page" [CLOSED] + - #52: "Add logout functionality" [OPEN] + - #53: "Add password reset" [CLOSED] + Status: 2/3 closed (67%) + ⏸️ Incomplete - keeping open + +βœ… Summary: + - Parent issues analyzed: 2 + - Issues closed: 1 + - Issues remaining open: 1 +`````` + +## Important Notes + +- This is a scheduled workflow that runs daily +- It catches any parent issues that should be closed but were missed by event-triggered workflows +- Use the GitHub MCP server tools to query issues and their relationships +- Be careful with recursive processing to avoid infinite loops +- Always verify the completion status before closing an issue +- Add clear, informative comments when closing issues for transparency + +## Guidelines + +- **Be Conservative**: Only close when absolutely certain all sub-issues are closed +- **Be Transparent**: Always add a comment explaining why the issue was closed +- **Be Efficient**: Process issues in batches to respect API rate limits +- **Be Recursive**: Check parent issues up the tree after closing +- **Be Informative**: Provide clear summaries of actions taken