GitHub Issue Triage

GitHub Issue Triage

Monitor open GitHub issues, match them to design docs, identify closable issues, and keep the issue tracker synchronized with actual development progress.

Quick Start

Most common usage:

# Full triage report - shows all issues, matches to design docs, suggests closures
.claude/skills/github-issue-triage/scripts/triage_report.sh

# Just list open issues with labels and age
.claude/skills/github-issue-triage/scripts/list_open_issues.sh

# Find issues that have been implemented (design docs in implemented/)
.claude/skills/github-issue-triage/scripts/find_closable.sh

# Match issues to planned design docs (shows what's being worked on)
.claude/skills/github-issue-triage/scripts/match_design_docs.sh --planned

When to Use This Skill

Invoke this skill when:

• User asks "what issues are open?", "check our issues", "triage issues"
• Starting a new development cycle and need to understand backlog
• After completing a release to identify closable issues
• Periodic housekeeping to keep issue tracker clean
• User wants to understand which issues are covered by design docs

Available Scripts

scripts/check_auth.sh

Verify GitHub CLI authentication matches expected user.

Usage:

.claude/skills/github-issue-triage/scripts/check_auth.sh

What it checks:

1. gh CLI is installed
2. User is authenticated to github.com
3. Active account matches github.expected_user in config

Exit codes:

• 0 - Auth OK, correct user active
• 1 - Auth failed or wrong user active

scripts/list_open_issues.sh [--json] [--labels LABELS]

List all open GitHub issues with details.

Usage:

.claude/skills/github-issue-triage/scripts/list_open_issues.sh
.claude/skills/github-issue-triage/scripts/list_open_issues.sh --json
.claude/skills/github-issue-triage/scripts/list_open_issues.sh --labels bug,enhancement

Output includes:

• Issue number and title
• Labels (bug, enhancement, etc.)
• Age (days since creation)
• Last updated date
• Assignee (if any)

scripts/match_design_docs.sh [--planned] [--implemented] [--all]

Match open issues to design documents.

Usage:

.claude/skills/github-issue-triage/scripts/match_design_docs.sh           # All matches
.claude/skills/github-issue-triage/scripts/match_design_docs.sh --planned # Only planned docs
.claude/skills/github-issue-triage/scripts/match_design_docs.sh --implemented # Only implemented

Matching strategy:

1. Exact issue number references (#123 in design doc)
2. Title keyword matching (significant words from issue title)
3. Bug ID matching (M-BUG-XXX patterns)

Output:

Issue #29: Parser crash on empty input
  Status: COVERED
  Design doc: design_docs/planned/v0_6_1/m-bug-parser-crash.md
  Match type: exact_reference (#29)

Issue #31: Add async support
  Status: NOT COVERED
  No matching design doc found
  Suggestion: Create design doc in design_docs/planned/v0_7_0/

scripts/find_closable.sh [--close] [--dry-run]

Find issues that have been implemented and can be closed.

Usage:

.claude/skills/github-issue-triage/scripts/find_closable.sh           # Report only
.claude/skills/github-issue-triage/scripts/find_closable.sh --dry-run # Preview close actions
.claude/skills/github-issue-triage/scripts/find_closable.sh --close   # Actually close issues

What it checks:

1. Issue referenced in design_docs/implemented/ directory
2. Issue mentioned in CHANGELOG.md
3. Issue keywords match implemented features

scripts/triage_report.sh [--output FILE]

Generate a complete triage report combining all analysis.

Usage:

.claude/skills/github-issue-triage/scripts/triage_report.sh
.claude/skills/github-issue-triage/scripts/triage_report.sh --output /tmp/triage.md

Report includes:

1. Summary: Total open, covered, closable, orphaned
2. Closable Issues: Ready to close (implemented)
3. Covered Issues: Have design docs (in progress)
4. Orphaned Issues: No design doc coverage (need attention)
5. Stale Issues: No activity in 30+ days
6. Recommendations: Suggested actions

Triage Workflow

1. Check Authentication

Always verify correct GitHub account:

.claude/skills/github-issue-triage/scripts/check_auth.sh

If wrong account:

gh auth switch --user MarkEdmondson1234

2. Generate Triage Report

.claude/skills/github-issue-triage/scripts/triage_report.sh

3. Handle Closable Issues

Review and close issues that have been implemented:

# Preview what would be closed
.claude/skills/github-issue-triage/scripts/find_closable.sh --dry-run

# Close with proper comments
.claude/skills/github-issue-triage/scripts/find_closable.sh --close

4. Review Orphaned Issues

For issues without design doc coverage:

1. Assess priority and feasibility
2. Create design doc if work should proceed: /design-doc-creator
3. Close with "won't fix" if out of scope
4. Add to backlog for future versions

5. Handle Stale Issues

For issues with no activity in 30+ days:

1. Check if still relevant
2. Add comment requesting update from reporter
3. Close if no response after additional time

Bot User Integration (sunholo-voight-kampff)

Status: ACTIVE - Bot is configured and ready to use.

Bot account: https://github.com/sunholo-voight-kampff

What Uses the Bot

Current Configuration

The bot is configured in ~/.ailang/config.yaml:

github:
  expected_user: sunholo-voight-kampff
  default_repo: sunholo-data/ailang

Switching Accounts

# Use bot (current)
gh auth switch --user sunholo-voight-kampff

# Use personal (update config too if using ailang messages --github)
gh auth switch --user MarkEdmondson1234

Benefits of Bot User

• Audit trail: All automated actions attributed to bot
• Rate limits: Separate from personal account limits
• Revocable access: Easy to disable without affecting personal auth
• CI/CD integration: Can use same token in automation
• Unified: Both gh CLI and ailang messages use same account

For detailed setup and troubleshooting, see resources/bot_user_guide.md

Configuration

Current config in ~/.ailang/config.yaml:

github:
  expected_user: sunholo-voight-kampff  # Bot account (active)
  default_repo: sunholo-data/ailang

Integration with Other Skills

With release-manager

# Before release: find issues to close
.claude/skills/github-issue-triage/scripts/find_closable.sh

# During release: close issues
.claude/skills/release-manager/scripts/collect_closable_issues.sh 0.6.1 --close

With design-doc-creator

# Find uncovered issues, then create design doc
.claude/skills/github-issue-triage/scripts/match_design_docs.sh --planned
# For uncovered issue #42:
/design-doc-creator M-ISSUE-42 "Fix for issue #42"

With sprint-planner

# Use triage report to inform sprint scope
.claude/skills/github-issue-triage/scripts/triage_report.sh --output /tmp/triage.md
# Include high-priority uncovered issues in sprint

Resources

Bot User Guide

See resources/bot_user_guide.md for complete bot account setup.

Triage Checklist

See resources/triage_checklist.md for step-by-step checklist.

Prerequisites

• GitHub CLI (gh) installed and authenticated
• Correct user active (gh auth status)
• Repository access (sunholo-data/ailang)
• ~/.ailang/config.yaml with github.expected_user

Notes

• All scripts check auth before making changes
• Close operations add proper comments with release/commit references
• Designed for AILANG repo but can be adapted for others
• Works with existing ailang messages GitHub integration