process-issues

# Process GitHub Issues

Automated workflow for processing GitHub Issues from repository.

## CRITICAL REQUIREMENTS

> **YOU MUST FOLLOW THESE RULES. NO EXCEPTIONS.**

### 1. BEADS IS MANDATORY

**EVERY issue MUST have a Beads task before fixing.** No direct fixes without tracking.

```bash
# ALWAYS run this FIRST for each issue:
bd create --type=<bug|task|feature> --priority=<1-3> --title="<issue_title>" --external-ref="gh-<number>"
bd update <task_id> --status=in_progress
```

### 2. READ ISSUE COMMENTS (MANDATORY)

**ALWAYS read comments to issues — they contain valuable insights:**

```bash
# View issue with all comments
gh issue view <number> --comments

# Or via API for structured data
gh api repos/{owner}/{repo}/issues/<number>/comments --jq '.[].body'
```

**What to analyze in comments:**

- **User clarifications**: Additional context about the problem
- **Suggested solutions**: Community/team members often propose fixes
- **Workarounds**: Temporary solutions that hint at root cause
- **Related issues**: Links to other issues with same problem
- **Screenshots/logs**: Additional debugging information

**Decision making for suggestions:**

| Suggestion Type       | Action                                          |
| --------------------- | ----------------------------------------------- |
| Clear fix with code   | Verify correctness, adopt if valid              |
| Architecture proposal | Evaluate complexity, discuss with user if major |
| Workaround            | Note it, but look for proper fix                |
| Conflicting advice    | Analyze trade-offs, choose best approach        |
| Outdated advice       | Check if still relevant to current codebase     |

**Include in analysis:**

```markdown
### Comments Analysis

- **Useful suggestions**: <list helpful comments>
- **Decision**: Adopt / Modify / Reject with reason
```

### 3. SEARCH SIMILAR PROBLEMS FIRST (MANDATORY)

**Before fixing ANY issue, search BOTH sources:**

#### 2a. Search in Beads (closed tasks)

```bash
# Search by keywords from issue title/body
bd search "<keyword>" --type=bug --status=closed
bd search "<keyword>" --type=task --status=closed

# Example searches:
bd search "silent failure"
bd search "Stage 6"
bd search "regeneration"
```

**What to look for in Beads:**

- Similar issue patterns in task titles
- Root cause analysis in task descriptions
- Fix approach and files changed

#### 2b. Search in GitHub (closed issues)

```bash
# Search closed issues
gh issue list --state closed --search "<keyword>"

# View specific closed issue for context
gh issue view <number>
```

#### 2c. If found similar resolved issue

1. **From Beads**: Read task description for root cause and fix approach
2. **From GitHub**: Read the closing comment — contains solution
3. Apply same solution pattern if applicable
4. **Reference in your fix**: `Similar to mc2-xxx / gh-NN. Same fix applied.`

### 4. CONTEXT7 IS MANDATORY

**ALWAYS query documentation before implementing:**

```
mcp__context7__resolve-library-id → mcp__context7__query-docs
```

**When to use:**

- React/Next.js patterns
- Supabase queries
- BullMQ job handling
- Any external library involved

### 5. TASK COMPLEXITY ROUTING

**Route tasks by complexity:**

| Complexity  | Examples                              | Action                   |
| ----------- | ------------------------------------- | ------------------------ |
| **Simple**  | Typo fix, single import, config value | Execute directly         |
| **Medium**  | Multi-file fix, migration, API change | **Delegate to subagent** |
| **Complex** | Architecture change, new feature      | Ask user first           |

**Subagent selection for MEDIUM tasks:**

| Domain           | Subagent                      | When                    |
| ---------------- | ----------------------------- | ----------------------- |
| DB/migrations    | `database-architect`          | Schema changes, RLS     |
| UI components    | `nextjs-ui-designer`          | New pages, components   |
| Backend services | `fullstack-nextjs-specialist` | APIs, workers           |
| Types            | `typescript-types-specialist` | Complex types, generics |
| Pipeline stages  | `stage-pipeline-specialist`   | Stages 1-7              |

### 6. ISSUE LABELS → PRIORITY MAPPING

| GitHub Label  | Priority | Description                   |
| ------------- | -------- | ----------------------------- |
| `bug`         | P1-P2    | Bug fix (severity determines) |
| `enhancement` | P2-P3    | Feature improvement           |
| `UX`          | P2       | User experience issue         |
| `A11Y`        | P3       | Accessibility                 |
| `feature`     | P3       | New feature request           |

### 7. BUG FIXING PRINCIPLES

> **This is PRODUCTION. Every bug matters.**

**Fix fundamentally, not superficially:**

- Find and fix the ROOT CAUSE, not just symptoms
- If error happens in function X but cause is in function Y → fix Y
- Don't add workarounds/hacks that mask the problem
- Ask: "Why did this happen?" until you reach the actual cause

**Quality over speed:**

- Take time to understand the full context
- Test the fix mentally: "What else could break?"
- Check for similar patterns elsewhere in codebase
- One good fix > multiple quick patches

---

## Usage

Invoke via: `/process-issues` or "обработай GitHub issues"

Optional arguments:

- `/process-issues --label=bug` — only bug issues
- `/process-issues --limit=5` — process max 5 issues
- `/process-issues 123` — process specific issue #123

---

## Workflow

### Step 1: Fetch Open Issues

```bash
# Get all open issues sorted by priority
gh issue list --state open --json number,title,labels,body,createdAt --limit 50

# Or filter by label
gh issue list --state open --label bug --json number,title,labels,body
```

### Step 2: Analyze Each Issue

For each open issue:

1. **Read issue details**:

   ```bash
   gh issue view <number>
   ```

2. **Read and analyze comments** (MANDATORY):

   ```bash
   #