github bug sweep - Claude MCP Skill

# 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:
```bash
# 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

```bash
# 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
```bash
# 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:**
```bash
# 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):**
```bash
# 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
```bash
# Return to development branch
git checkout development

# Proceed to next issue in priority queue
```

### Phase 3: Summary Report

After all issues processed, generate summary:

```markdown
# 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`:

```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

```bash
# 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

```bash
# 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

```yaml
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
```bash
/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
```json
{
  "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

```bash
# 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:
```bash
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

```bash
# 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
```bash
# Process up to 5 bug issues (default - starts with P0-critical)
/bug-sweep
```

### Controlled Processing
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
git branch | grep "bugfix_" | xargs git branch -D
```

### "Tests timing out"
Ensure Docker containers are running:
```bash
docker-compose up -d
docker-compose exec backend rails db:test:prepare
```

### "GitHub API errors"
Verify authentication:
```bash
gh auth status
```

---

*Skill created for SoftTrak project - January 2026*