sipherxyz/github-assign-issue

Configuration

This skill reads project-specific values from skills.config.json at the repository root. Required keys: github.repo, github.owner, github.project_number, milestones.*, team.* If not found, prompt the user for repository and project details.

GitHub Issue Auto-Assignment Skill

Role: Issue Assignment Automation Scope: Project-wide issue routing and assignment Platform: Windows + gh CLI Repository: {github.repo}

Objective

Analyze GitHub issues and recommend (or auto-assign) appropriate engineers based on domain expertise matrix, issue labels, title keywords, and referenced file paths.

Prerequisites

1. gh CLI authenticated: gh auth status
2. Engineer matrix file exists at {project-root}/claude-agents/team/engineer-matrix.md
3. Issue must be in the {github.repo} repository

Dynamic Context Resolution

{CWD} = Current Working Directory
{ProjectRoot} = {project.root}
{MatrixPath} = {ProjectRoot}/claude-agents/team/engineer-matrix.md
{RepoOwner} = {github.owner}
{RepoName} = s2
{FallbackAssignee} = {team.principal.handle}

Workflow

Step 1: Parse Input

Accept GitHub issue URL or issue number:

Input formats:
- Full URL: https://github.com/{github.repo}/issues/123
- Short URL: {github.repo}#123
- Number only: 123 (assumes current repo)

Extract issue number using regex: issues/(\d+) or #(\d+) or ^(\d+)$

Step 2: Fetch Issue Details

gh issue view {number} --json number,title,body,labels,assignees --repo {github.repo}

Extract:

• Issue number, title, body text
• Current labels (array of label names)
• Current assignees (may be empty)

Validate:

• If issue not found → Error: "Issue #{number} not found"
• If issue already assigned → Warning: "Issue already assigned to @{user}. Override? [y/N]"
• If --force flag → Skip warning, proceed with reassignment

Step 3: Load Engineer Matrix

Read matrix file from: {ProjectRoot}/claude-agents/team/engineer-matrix.md

Parse into data structures:

• Engineers: Map of username → {name, role, availability}
• Domains: Map of label → {primary, backup, keywords}
• FilePatterns: Map of pattern → domain

Validate:

• If matrix file missing → Error: "Engineer matrix not found at {path}. Run with --init-matrix to create template."
• If matrix malformed → Error: "Matrix parse error: {details}"

Step 4: Detect Issue Domain

Multi-signal domain detection with weighted scoring:

Signal 1: Labels (weight: 10)

For each issue label:
  If label exists in Domains map:
    Add domain with weight = 10

Signal 2: Title Keywords (weight: 5)

For each domain in Domains map:
  For each keyword in domain.keywords:
    If keyword in issue.title (case-insensitive):
      Add domain with weight = 5

Signal 3: File Path Patterns (weight: 3)

Extract file paths from issue body using pattern: `/[A-Za-z_]+/[^\s]+\.(cpp|h|uasset)`
For each path:
  For each pattern in FilePatterns:
    If path matches pattern:
      Add domain with weight = 3

Signal 4: Body Keywords (weight: 2)

For each domain in Domains map:
  For each keyword in domain.keywords:
    If keyword in issue.body (case-insensitive, first 1000 chars):
      Add domain with weight = 2

Aggregate:

Sum weights per domain
Sort by weight descending
Primary domain = highest weight

Step 5: Match Engineers

If total_weight >= 5:
  domain_mapping = Domains[primary_domain]
  primary_engineer = domain_mapping.primary
  backup_engineer = domain_mapping.backup

  If Engineers[primary_engineer].availability != 'U':
    recommended = primary_engineer
    reasoning = "Primary owner of '{domain}'"
    confidence = "HIGH" if weight >= 15 else "MEDIUM" if weight >= 10 else "LOW"
  Else If backup_engineer AND Engineers[backup_engineer].availability != 'U':
    recommended = backup_engineer
    reasoning = "Backup for '{domain}' (primary unavailable)"
    confidence = "MEDIUM"
  Else:
    recommended = {FallbackAssignee}
    reasoning = "Fallback owner (no available engineer for domain)"
    confidence = "LOW"
Else:
  recommended = {FallbackAssignee}
  reasoning = "Default owner (no domain match)"
  confidence = "DEFAULT"

Step 6: Present Recommendation

═══════════════════════════════════════════════════════════════
ISSUE ASSIGNMENT RECOMMENDATION
═══════════════════════════════════════════════════════════════

Issue #123: Fix combo system animation desync
URL: https://github.com/{github.repo}/issues/123

Current Assignees: (none)
Labels: combat, Engineering, bug

═══════════════════════════════════════════════════════════════
ANALYSIS
═══════════════════════════════════════════════════════════════

Detected Domains:
  1. combat      (weight: 15) - Label + keyword "combo"
  2. system      (weight: 2)  - Body keyword "framework"

Signal Breakdown:
  - Label "combat"     → combat (+10)
  - Title "combo"      → combat (+5)
  - Body "framework"   → system (+2)

═══════════════════════════════════════════════════════════════
RECOMMENDATION
═══════════════════════════════════════════════════════════════

Assignee:   @DuyTranSipher (Duy Tran) - Game Engineer
Reasoning:  Primary owner of 'combat' domain
Confidence: HIGH

Backup:     @{team.principal.handle} (Loc Bui) - Principal Engineer

═══════════════════════════════════════════════════════════════

Options:
  1. Assign to @DuyTranSipher
  2. Assign to @{team.principal.handle} (backup)
  3. Select different assignee
  4. Skip assignment

Your choice (1/2/3/4): _

If --quick flag: Skip prompt, auto-assign to recommended.

Step 7: Execute Assignment

If user selects option 1 or 2 (or --quick mode):

gh issue edit {number} --add-assignee {username} --repo {github.repo}

Validate response:

• Success → Proceed to Step 8
• Failure → Error: "Assignment failed: {error}"

Step 8: Return Result

Assignment complete!

Issue #123: Fix combo system animation desync
Assigned to: @DuyTranSipher (Duy Tran)
Domain: combat
Confidence: HIGH

View issue: https://github.com/{github.repo}/issues/123

Return Values (for programmatic use):

IssueNumber: 123
AssignedTo: DuyTranSipher
Domain: combat
Confidence: HIGH

---

Error Handling

Error: Issue Not Found

Error: Issue #9999 not found in {github.repo}

Verify issue exists: gh issue view 9999 --web --repo {github.repo}

Error: Matrix Not Found

Error: Engineer matrix not found

Expected: {project.root}\claude-agents\team\engineer-matrix.md

Run: /github-assign-issue --init-matrix

Error: Already Assigned

Warning: Issue #123 already assigned to @existinguser

Options:
  1. Add @DuyTranSipher as additional assignee
  2. Replace with @DuyTranSipher
  3. Keep current assignment
  4. Cancel

Your choice: _

Error: Engineer Unavailable

Warning: Primary engineer @DuyTranSipher is unavailable (U)

Falling back to backup: @{team.principal.handle}

Continue with backup assignment? (y/N): _

---

Advanced Usage

Dry Run Mode

Preview without executing:

/github-assign-issue 123 --dry-run

Shows recommendation but does not modify issue.

Quick Mode

Auto-assign without confirmation:

/github-assign-issue 123 --quick

Immediately assigns to recommended engineer.

Force Mode

Override existing assignment:

/github-assign-issue 123 --force

Skips "already assigned" warning.

Batch Mode

Process multiple issues:

/github-assign-issue --batch 100,101,102,103

Workflow:

1. Fetch all issues in parallel
2. Generate recommendations for each
3. Present summary table:

═══════════════════════════════════════════════════════════════
BATCH ASSIGNMENT PREVIEW
═══════════════════════════════════════════════════════════════

| Issue | Title                    | Domain  | Assignee         | Confidence |
|-------|--------------------------|---------|------------------|------------|
| #100  | Fix combo animation      | combat  | @DuyTranSipher   | HIGH       |
| #101  | UI menu flicker          | UXUI    | @HungLeSipher    | MEDIUM     |
| #102  | AI pathing stuck         | ai      | @KhoaLeSipher    | HIGH       |
| #103  | General cleanup          | -       | @{team.principal.handle}       | DEFAULT    |

═══════════════════════════════════════════════════════════════

Options:
  1. Assign all as shown
  2. Review individually
  3. Cancel

Your choice: _

Initialize Matrix

Create template matrix file:

/github-assign-issue --init-matrix

Creates claude-agents/team/engineer-matrix.md with default template if not exists.

Update Availability

Quick availability update:

/github-assign-issue --set-availability @DuyTranSipher U

Updates engineer's status to Unavailable in matrix file.

---

Matching Algorithm Details

Weight Calculation

Domain Score = (Label Matches × 10) + (Title Keywords × 5) + (File Paths × 3) + (Body Keywords × 2)

Confidence Levels

| Score | Confidence | Description | |-------|------------|-------------| | >= 15 | HIGH | Strong signal (label + keyword) | | 10-14 | MEDIUM | Single strong signal (label only) | | 5-9 | LOW | Weak signals (keywords/paths only) | | < 5 | DEFAULT | Fallback to @{team.principal.handle} |

Tie-Breaking Rules

1. If two domains have equal weight, prefer the one with label match
2. If still tied, prefer alphabetically first domain
3. If engineer is Primary for multiple matched domains, boost confidence

---

Integration with Other Skills

Called After github-create-issue

After creating an issue, optionally invoke this skill:

After issue creation:
  If user wants assignment:
    Invoke /github-assign-issue {IssueNumber} --quick

Called by Agentic Bug Fix System

When processing bugs, auto-assign for tracking:

After bug analysis:
  Invoke /github-assign-issue {IssueNumber}
  Log assignment for sprint tracking

---

Success Criteria

• [ ] Parses GitHub issue URL or number
• [ ] Fetches issue details via gh CLI
• [ ] Loads and parses engineer matrix
• [ ] Detects domain from labels (weight: 10)
• [ ] Detects domain from title keywords (weight: 5)
• [ ] Detects domain from file path patterns (weight: 3)
• [ ] Detects domain from body keywords (weight: 2)
• [ ] Aggregates signals with correct weights
• [ ] Matches engineer based on domain ownership
• [ ] Checks engineer availability
• [ ] Falls back to backup or @{team.principal.handle}
• [ ] Presents recommendation with confidence level
• [ ] Executes assignment via gh CLI
• [ ] Handles missing matrix file (--init-matrix)
• [ ] Handles no domain match (fallback to @{team.principal.handle})
• [ ] Handles all engineers unavailable
• [ ] Handles already assigned issues
• [ ] Supports --dry-run mode
• [ ] Supports --quick mode
• [ ] Supports --force mode
• [ ] Supports --batch mode

---

Notes

• All gh commands target --repo {github.repo} explicitly
• Matrix file is plain markdown for easy manual editing
• Availability must be manually updated by team leads
• Fallback owner is @{team.principal.handle} for all unmatched issues
• No Claude attribution footer per CLAUDE.md guidelines

Legacy Metadata

skill: github-assign-issue
invoke: /github-workflow:github-assign-issue
type: workflow
category: github
scope: project-root