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

Tool	Uses Bot?
gh issue close/comment	Yes (via gh auth)
ailang messages send --github	Yes (via config)
ailang messages import-github	Yes (via config)
Issue triage scripts	Yes (uses gh CLI)

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