GitHub Bug Sweep - Automated Issue Resolution Orchestration

Skill Type: Orchestration workflow for sequential GitHub Issue bug resolution
Version: 1.0.0
Author: SoftTrak Development Team

Overview

This skill orchestrates sequential subagent deployment to investigate and resolve GitHub Issues labeled as bugs. Each issue is processed one at a time to avoid conflicts, with full documentation and PR creation.

Triggers

• User requests bulk bug resolution from GitHub Issues
• /bug-sweep or /github-bug-sweep command
• Request to process open GitHub Issues systematically

Prerequisites

• GitHub CLI (gh) authenticated and configured
• Git repository with development branch as base
• Docker environment running for test execution
• Write access to create branches and PRs

⚠️ CRITICAL: Branch Workflow Requirements

ALL bugfix branches MUST:

1. Be created FROM the development branch (not main)
2. Have PRs targeting the development branch (not main)

This is NON-NEGOTIABLE. The main branch is protected and receives code only through controlled merges from development. Direct PRs to main bypass the standard code review and integration testing workflow.

Before creating any branch or PR, ALWAYS verify:

# Verify you're on development
git branch --show-current  # Should output: development

# Verify PR base is development
gh pr create --base development ...  # ALWAYS use --base development

Workflow

Phase 1: Issue Discovery & Prioritization

# Fetch all open bug issues
gh issue list --state open --label bug --json number,title,labels,createdAt,body

Priority Scoring Algorithm:

CRITICAL: Issues MUST be selected in strict priority label order: P0 → P1 → P2 → P3.
Within each priority tier, secondary scoring factors determine order.

Label	Score	Notes
P0-critical	+100	HIGHEST - System down, security breach, data loss
P1-high	+50	High priority - Major functionality broken
security	+8	Security vulnerabilities (additive to P-level)
compliance	+7	Regulatory requirements
P2-medium	+25	Medium priority - Important but not urgent
performance	+4	Performance issues
P3-low	+10	Low priority - Minor issues, polish
needs-triage	-3	Reduces priority until triaged

Formula:

Score = (P0-critical × 100) + (P1-high × 50) + (P2-medium × 25) + (P3-low × 10)
      + (security × 8) + (compliance × 7) + (performance × 4)
      + (days_open × 0.5) - (needs-triage × 3)

Selection Order:

1. Primary: Priority label (P0 > P1 > P2 > P3 > unlabeled)
2. Secondary: Total score within same priority tier
3. Tie-breaker: Fewer comments, then older creation date

Example Priority Order:

1. Issue #470 [P0-critical] Score: 108  ← Always first
2. Issue #465 [P0-critical] Score: 100
3. Issue #554 [P1-high]     Score: 58   ← After ALL P0s
4. Issue #523 [P2-medium]   Score: 33   ← After ALL P1s
5. Issue #489 [P3-low]      Score: 14   ← After ALL P2s

Process issues in descending score order, respecting priority tier boundaries.

Extended Priority Scoring

In addition to label-based scoring, analyze issue body for:

Pattern	Score Adjustment	Rationale
"production" or "prod"	+3	Production impact
"customer" or "user report"	+2	Customer-facing
"regression"	+2	Previously worked
"blocker" or "blocking"	+2	Blocking other work
"workaround" or "work around"	-1	Has mitigation
"edge case" or "rare"	-1	Lower frequency
Stack trace present	+1	Good reproduction info
Steps to reproduce present	+1	Easy to debug

Body Analysis Limits

• Only first 1000 characters analyzed
• Case-insensitive matching
• Maximum body score adjustment: ±5 points

Example

Issue #554: "External service calls blocking request thread"

• Labels: [bug, P2-medium] → Base score: 5
• Body contains "production" → +3
• Body contains "blocking" → +2
• Body has stack trace → +1
• Final Score: 11 (high priority)

Phase 2: Per-Issue Resolution Loop

For each issue in priority order:

Step 1: Pre-Flight Setup

# Ensure we're on development and up to date
git checkout development
git pull origin development

# Create bugfix branch
# Sanitize title: lowercase, replace spaces with hyphens, remove special chars
BRANCH_NAME="bugfix_${ISSUE_NUMBER}_$(echo "${ISSUE_TITLE}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | head -c 50)"
git checkout -b "$BRANCH_NAME"

Step 2: Subagent Delegation

Spawn a subagent with the following prompt:

/sc:troubleshoot GitHub Issue #[NUMBER]: [TITLE]

## Issue Details
[Full issue body from GitHub]

## Labels
[List of labels]

## Constraints
- Maximum time: 30 minutes
- Base branch: development
- Current branch: [BRANCH_NAME]
- Test command: docker-compose exec backend bundle exec rails test
- Follow CLAUDE.md style guidelines

## Success Criteria
1. Root cause identified and documented
2. Fix implemented following project conventions
3. All existing tests pass
4. New tests added if appropriate
5. No unrelated code modifications

## Required Deliverables
If successful:
- Clear explanation of root cause
- Description of fix implemented
- Test results summary

If unsuccessful:
- Investigation findings
- Specific blockers encountered
- Recommendations for manual review

## Context
This is part of an automated bug sweep. Document findings thoroughly
for the GitHub Issue comment.

Step 3: Post-Resolution Actions

On Success:

# Stage and commit changes
git add -A
git commit -m "fix(#${ISSUE_NUMBER}): ${SHORT_DESCRIPTION}

Resolves GitHub Issue #${ISSUE_NUMBER}

Root cause: ${ROOT_CAUSE_SUMMARY}
Fix: ${FIX_SUMMARY}

Co-Authored-By: Claude Code <noreply@anthropic.com>"

# Push branch
git push -u origin "$BRANCH_NAME"

# Create PR
gh pr create \
  --base development \
  --title "Fix #${ISSUE_NUMBER}: ${ISSUE_TITLE}" \
  --body "## Summary
Automated fix for GitHub Issue #${ISSUE_NUMBER}

## Root Cause
${ROOT_CAUSE_DETAILS}

## Changes Made
${CHANGES_DESCRIPTION}

## Test Results
${TEST_RESULTS}

## Verification
- [ ] Tests pass
- [ ] Code follows project conventions
- [ ] No unrelated changes

---
Generated by GitHub Bug Sweep automation"

# Add comment to issue
gh issue comment ${ISSUE_NUMBER} --body "## Automated Investigation Complete

**Status:** Fix implemented and PR created

### Root Cause
${ROOT_CAUSE_DETAILS}

### Resolution
${RESOLUTION_DETAILS}

### Pull Request
See PR #${PR_NUMBER} for the fix.

---
*Automated by GitHub Bug Sweep*"

# Close the issue
gh issue close ${ISSUE_NUMBER} --comment "Resolved in PR #${PR_NUMBER}"

On Failure (Unable to Fix):

# Clean up branch if no meaningful changes
git checkout development
git branch -D "$BRANCH_NAME" 2>/dev/null || true

# Add detailed comment to issue
gh issue comment ${ISSUE_NUMBER} --body "## Automated Investigation Complete

**Status:** Requires manual review

### Investigation Findings
${INVESTIGATION_DETAILS}

### Blockers Encountered
${BLOCKERS_LIST}

### Recommendations
${RECOMMENDATIONS}

### Files Examined
${FILES_EXAMINED}

---
*Automated by GitHub Bug Sweep - Flagged for manual review*"

# Add needs-review label
gh issue edit ${ISSUE_NUMBER} --add-label "needs-review"

Step 4: Cleanup & Next Issue

# Return to development branch
git checkout development

# Proceed to next issue in priority queue

Phase 3: Summary Report

After all issues processed, generate summary:

# GitHub Bug Sweep Summary

**Date:** [TIMESTAMP]
**Total Issues Processed:** [COUNT]

## Successfully Resolved
| Issue | Title | PR |
|-------|-------|-----|
| #XXX | Title | #YYY |

## Flagged for Review
| Issue | Title | Reason |
|-------|-------|--------|
| #XXX | Title | Blocker description |

## Remaining Open Issues
[List any issues not yet processed]

Configuration

Command Parameters

Parameter	Default	Description
--max-issues N	5	Maximum issues to process (1-50)
--dry-run	false	Analyze without making changes
--priority-only	false	Only process P0/P1/P2 issues (skip P3-low)
--p0-only	false	Only process P0-critical issues
--labels LABELS	bug	Comma-separated label filter
--skip-closed-recently N	7	Skip issues closed in last N days
--issue NUMBER	null	Process single specific issue
--start-from NUMBER	null	Resume from specific issue number
--reset-circuit	false	Reset circuit breaker state

Configuration File

Optional project-level configuration in .bugsweep.json:

{
  "defaults": {
    "max_issues": 10,
    "issue_timeout": 30,
    "labels": ["bug"],
    "auto_merge": false
  },
  "priority_overrides": {
    "security": 12,
    "compliance": 10
  },
  "resolver_preferences": {
    "frontend": "frontend-debug",
    "backend": "sc-troubleshoot"
  },
  "excluded_paths": [
    "vendor/",
    "node_modules/"
  ],
  "notification": {
    "slack_channel": "#all-softtrak",
    "on_complete": true,
    "on_failure": true
  }
}

Configuration Precedence

1. Command-line flags (highest)
2. .bugsweep.json in repository root
3. ~/.claude/skills/github-bug-sweep/defaults.json
4. Built-in defaults (lowest)

Relationship to Other Skills

This configuration follows the pattern established by:

• frontend-debug: .frontend-qc.json
• frontend-qc: .frontend-qc.json

Consider sharing base configuration schema across debugging skills.

Scope Examples

# Test run with single issue (will pick highest priority P0)
/bugsweep --max-issues 1

# Process ONLY P0-critical issues (recommended first)
/bugsweep --p0-only

# Process P0/P1/P2 issues (skip low priority)
/bugsweep --priority-only --max-issues 10

# Dry run to preview prioritization order
/bugsweep --dry-run

# Process specific issue
/bugsweep --issue 554

# Full sweep with increased limit
/bugsweep --max-issues 20

# Filter by specific priority label
/bugsweep --labels "bug,P0-critical"
/bugsweep --labels "bug,P1-high"

Dry Run Mode

When --dry-run is enabled:

Phase	Normal Behavior	Dry Run Behavior
Issue Fetch	Fetch from GitHub	Fetch from GitHub
Prioritization	Score and sort	Score and sort
Classification	Classify type	Classify type
Resolution	Attempt fix	Skip - Log "Would attempt fix"
PR Creation	Create PR	Skip - Log "Would create PR"
Label Updates	Add labels	Skip - Log "Would add label"

Dry Run Output

=== Bug Sweep Dry Run ===

Issues Matched: 60
After Filtering: 45 (open, bug label)

Priority Order (P0 → P1 → P2 → P3):

[P0-CRITICAL] - 30 issues
1. #470 - "XSS Vulnerability in workflow_editor" (Score: 108, Type: SECURITY)
2. #465 - "SQL Injection in Data Validator" (Score: 100, Type: SECURITY)
3. #464 - "Race Condition in Circuit Breaker" (Score: 100, Type: BACKEND)
...

[P1-HIGH] - 5 issues
31. #554 - "External service calls blocking" (Score: 58, Type: BACKEND)
32. #523 - "Dashboard chart not updating" (Score: 50, Type: FRONTEND)
...

[P2-MEDIUM] - 8 issues
36. #489 - "Audit log pagination broken" (Score: 33, Type: BACKEND)
...

[P3-LOW] - 2 issues
44. #712 - "Core Services: No code coverage" (Score: 14, Type: BACKEND)
...

With --max-issues 5:
  Would process: #470, #465, #464, #463, #462 (all P0-critical)
  Would skip: 40 remaining issues

Estimated Time: 2.5 hours (based on 30 min/issue average)

To execute: /bugsweep --max-issues 5

Use Cases

1. Preview prioritization before committing time
2. Validate configuration without side effects
3. Estimate scope for time planning
4. Debug classification logic

Time Limits

• Per-issue maximum: 30 minutes
• Investigation phase: 10 minutes
• Implementation phase: 15 minutes
• Testing/documentation: 5 minutes

Branch Naming

Pattern: bugfix_[issue_number]_[sanitized_title]

• Lowercase
• Spaces replaced with hyphens
• Special characters removed
• Maximum 60 characters

Labels Used

• needs-review - Added when automated fix fails
• automated-fix - Added to PRs created by this workflow
• bugsweep-timeout - Added when issue exceeds timeout

Timeout Configuration

Timeout	Default	Description
issue_timeout	30 min	Max time per issue
test_timeout	10 min	Max time for test suite
browser_timeout	5 min	Max time for browser verification
total_timeout	4 hours	Max time for entire sweep

Timeout Behavior

Per-Issue Timeout (30 min default)

When an issue exceeds its timeout:

1. Save current state to checkpoint
2. Revert uncommitted changes
3. Add bugsweep-timeout label to issue
4. Log: "Issue #N exceeded 30 min timeout"
5. Increment timeout counter
6. Check circuit breaker (3 timeouts = trip)
7. Continue to next issue

Test Suite Timeout (10 min default)

When tests exceed timeout:

1. Kill test process
2. Treat as test failure (not timeout)
3. Log: "Test suite for #N exceeded timeout"
4. Continue with fix attempt (may work anyway)

Browser Verification Timeout (5 min default)

When browser automation exceeds timeout:

1. Capture current screenshot
2. Log browser console
3. Mark verification as INCONCLUSIVE
4. Require manual verification before merge

Total Sweep Timeout (4 hours default)

When total time exceeds limit:

1. Complete current issue (if within issue timeout)
2. Generate partial summary
3. Create resume checkpoint
4. Log: "Sweep timeout after N issues (M remaining)"
5. Exit with PARTIAL_SUCCESS status

Timeout Escalation

Timeout Count	Action
1	Log and continue
2	Log warning, reduce remaining issue timeouts by 20%
3	Trip circuit breaker

Timeout Override Syntax

# Extend issue timeout for complex fixes
/bugsweep --issue-timeout 60

# Reduce for quick sweep
/bugsweep --issue-timeout 15 --max-issues 10

# Extend total sweep timeout
/bugsweep --total-timeout 6h

Resilience Patterns

Circuit Breaker

The skill implements a circuit breaker to prevent cascading failures:

State	Behavior	Transition
CLOSED	Normal processing	Opens after 3 consecutive failures
OPEN	Skip remaining issues	Closes after manual reset or new session
HALF-OPEN	Try 1 issue	Returns to CLOSED on success, OPEN on failure

Configuration

circuit_breaker:
  failure_threshold: 3          # Consecutive failures to trip
  reset_timeout: null           # Manual reset required
  half_open_max_calls: 1        # Test calls in half-open state

Failure Categories

Not all failures trip the circuit breaker:

Category	Trips Breaker	Rationale
Test failures (fixable)	No	Expected during debugging
Missing dependencies	Yes	Likely affects multiple issues
Permission errors	Yes	Systemic issue
Timeout exceeded	Yes	Resource exhaustion
Parse/syntax errors	No	Issue-specific

State Tracking

The orchestrator maintains circuit state in session:

CIRCUIT_STATE: CLOSED
CONSECUTIVE_FAILURES: 0
LAST_FAILURE_REASON: null

Manual Reset Command

/bugsweep --reset-circuit

Pre-Resolution Check

Before attempting each issue:

1. Check circuit breaker state
2. If OPEN: Log skip reason, increment issues_circuit_skipped counter
3. If HALF-OPEN: Attempt resolution, transition based on result
4. If CLOSED: Proceed normally

Post-Resolution Update

After each resolution attempt:

1. If SUCCESS: Reset CONSECUTIVE_FAILURES to 0
2. If FAILURE:
   • Increment CONSECUTIVE_FAILURES
   • Categorize failure type
   • If breaker-eligible failure AND count >= threshold: Set state to OPEN
   • Log failure with category for post-mortem analysis

State Management

Checkpoint System

The skill maintains state for resume capability:

Checkpoint File Location

~/.claude/skills/github-bug-sweep/.bugsweep-state.json

Checkpoint Schema

{
  "session_id": "uuid-v4",
  "started_at": "2026-01-17T10:00:00Z",
  "last_checkpoint": "2026-01-17T11:30:00Z",
  "status": "IN_PROGRESS",
  "circuit_state": "CLOSED",
  "consecutive_failures": 0,
  "configuration": {
    "max_issues": 10,
    "dry_run": false,
    "labels": ["bug"]
  },
  "issues": {
    "total_matched": 30,
    "prioritized_list": [554, 523, 489],
    "processed": [
      {"number": 554, "status": "FIXED", "pr": 601},
      {"number": 523, "status": "SKIPPED", "reason": "cannot_reproduce"}
    ],
    "current": null,
    "remaining": [489, 456]
  },
  "metrics": {
    "issues_fixed": 1,
    "issues_skipped": 1,
    "issues_failed": 0,
    "total_time_seconds": 5400
  }
}

Checkpoint Triggers

Checkpoints are saved:

1. After each issue is processed (success or failure)
2. Before starting browser verification
3. Every 10 minutes during long-running fixes
4. On graceful shutdown signal
5. On timeout

Resume Behavior

# Resume from last checkpoint
/bugsweep --resume

# Resume with modified parameters (uses saved issue list)
/bugsweep --resume --max-issues 5

# Discard checkpoint and start fresh
/bugsweep --fresh

# View checkpoint status without resuming
/bugsweep --status

Resume Logic

1. Check for existing checkpoint file
2. If found and status != COMPLETED:
   • Display checkpoint summary
   • Ask: "Resume from checkpoint? (Y/n/status)"
   • If Y: Load state, continue from remaining list
   • If n: Archive old checkpoint, start fresh
   • If status: Display detailed state, ask again
3. If not found or status == COMPLETED:
   • Start fresh sweep

Checkpoint Archival

Completed checkpoints are archived to:

~/.claude/skills/github-bug-sweep/.checkpoints/
  2026-01-17_10-00-00_completed.json
  2026-01-16_14-30-00_interrupted.json

Retention: Last 10 checkpoints kept, older deleted automatically.

Error Handling

Git Conflicts

If branch creation fails due to existing branch:

git branch -D "bugfix_${ISSUE_NUMBER}_*" 2>/dev/null
# Retry branch creation

Test Failures

If tests fail after fix:

1. Document which tests failed
2. Attempt to identify if failure is related to fix
3. If related: iterate on fix (within time limit)
4. If unrelated: note pre-existing failure, proceed with PR

API Rate Limits

If GitHub API rate limited:

1. Wait 60 seconds
2. Retry operation
3. If persistent, pause workflow and notify

Edge Cases & Error Handling

Scenario Matrix

Scenario	Expected Behavior	Logging
No open bug issues	Exit gracefully with success message	INFO: "No issues match criteria"
Issue closed during processing	Skip issue, log reason, continue	WARN: "Issue #N closed externally"
Issue reassigned during processing	Complete current fix, note in PR	INFO: "Issue reassigned, fix still valid"
Tests pass before any changes	Verify reproduction, close if resolved	INFO: "Issue may be resolved, verifying"
Cannot reproduce issue	Add needs-info label, comment, skip	INFO: "Cannot reproduce #N"
Fix introduces new test failures	Revert changes, log failure, continue	ERROR: "Fix for #N broke other tests"
Repository rate-limited	Pause 60s, retry with backoff	WARN: "Rate limited, pausing"
No write permissions	Abort entire sweep	FATAL: "Missing repository permissions"

Automatic Labels

The skill may add these labels during processing:

Label	When Applied
needs-info	Cannot reproduce issue
wontfix	Issue is by design (requires approval)
duplicate	Identical to another open issue
in-progress	Currently being worked on
bugsweep-attempted	Skill attempted but couldn't resolve

Recovery Actions

Issue Already Has Open PR

1. Check if PR is stale (>7 days no activity)
2. If stale: Comment offering to take over, wait 24h
3. If active: Skip issue, add to "deferred" list
4. Log: "Issue #N has active PR #M, skipping"

Merge Conflicts During PR

1. Attempt automatic rebase
2. If conflicts persist: Close PR, recreate from fresh branch
3. If still fails: Mark issue as bugsweep-attempted, skip

Branch Already Exists

1. Check if branch is stale (>14 days)
2. If stale: Delete and recreate
3. If recent: Use numbered suffix (e.g., fix/issue-123-v2)

Branch Cleanup

Automatic Cleanup

Branches are automatically deleted:

1. After PR merge: Immediately upon merge
2. After PR close: If closed without merge
3. Stale branches: fix/issue-* branches with no PR after 7 days

Branch Naming Convention

fix/issue-{number}-{short-description}

Examples:

• fix/issue-554-external-service-blocking
• fix/issue-523-dashboard-chart

Note: The skill also accepts the legacy format bugfix_[issue_number]_[title] for compatibility.

Cleanup Command

# Clean up all stale bugsweep branches
/bugsweep --cleanup-branches

# Preview only
/bugsweep --cleanup-branches --dry-run

Protection

Never delete:

• Branches with open PRs
• Branches with commits not in any PR
• Branches created by other users
• Non-bugsweep branches (not matching fix/issue-* or bugfix_*)

Usage Examples

Basic Invocation

# Process up to 5 bug issues (default - starts with P0-critical)
/bug-sweep

Controlled Processing

# Process single issue for testing (picks highest priority P0)
/bug-sweep --max-issues 1

# Process specific issue by number
/bug-sweep --issue 554

# Process up to 20 issues
/bug-sweep --max-issues 20

Priority-Based Filtering

# RECOMMENDED: Process only P0-critical issues first
/bug-sweep --p0-only

# Process P0/P1/P2 issues (skip P3-low)
/bug-sweep --priority-only

# Filter by specific priority label
/bug-sweep --labels "bug,P0-critical"
/bug-sweep --labels "bug,P1-high"

# Multiple labels (comma-separated)
/bug-sweep --labels "bug,security"

# Combine filters
/bug-sweep --priority-only --max-issues 10 --labels "bug,performance"

Preview & Testing

# Dry run - analyze and prioritize without changes
/bug-sweep --dry-run

# Dry run to see P0-critical issues
/bug-sweep --dry-run --p0-only

# Dry run with priority filter
/bug-sweep --dry-run --priority-only

Resume & Recovery

# Resume from specific issue number
/bug-sweep --start-from 525

# Reset circuit breaker after failures
/bug-sweep --reset-circuit

# Skip recently closed issues (default: 7 days)
/bug-sweep --skip-closed-recently 14

Integration with SuperClaude

This skill integrates with:

• /sc:pm - Project manager orchestration
• /sc:troubleshoot - Individual issue investigation
• /sc:git - Branch and PR management

Orchestrator Prompt Template

/sc:pm orchestrate sequential GitHub bug resolution

## Mode
Sequential subagent deployment - one issue at a time

## Priority Algorithm
Select issues in strict priority order: P0-critical → P1-high → P2-medium → P3-low
Score within tier: P0(100) + P1(50) + P2(25) + P3(10) + security(8) + compliance(7) + performance(4) + age(0.5/day) - needs-triage(3)

## Per-Issue Workflow
1. Create branch: bugfix_[id]_[name] from development
2. Delegate to subagent: /sc:troubleshoot with 30-minute limit
3. On success: commit, push, PR, comment, close issue
4. On failure: comment findings, add needs-review label
5. Return to development, proceed to next issue

## Constraints
- Sequential only (no parallel)
- 30 minutes max per issue
- Tests must pass for success
- Full documentation in GitHub comments

## Continue Until
All open bug issues are either:
- Closed with PR
- Labeled needs-review

Maintenance

Updating Priority Algorithm

Edit the scoring weights in Phase 1 based on team priorities.

Adding New Labels

Update the priority scoring to include new label types.

Adjusting Time Limits

Modify the Configuration section time values as needed.

Troubleshooting

"Branch already exists"

A previous run may have left branches. Clean up with:

git branch | grep "bugfix_" | xargs git branch -D

"Tests timing out"

Ensure Docker containers are running:

docker-compose up -d
docker-compose exec backend rails db:test:prepare

"GitHub API errors"

Verify authentication:

gh auth status

---

Skill created for SoftTrak project - January 2026