process-issues

name: process-issues description: 'Process GitHub Issues: fetch, prioritize (scoring matrix), create Beads tasks with dependencies, then auto-fix by priority order' version: 2.0.0

Process GitHub Issues

End-to-end workflow: fetch open GitHub Issues → analyze & score → create Beads tasks with dependency graph → auto-execute fixes by priority.

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.

# ALWAYS run this FIRST for each issue:
bd create --type=<bug|task|feature> --priority=<0-4> --title="<issue_title>" --external-ref="gh-<number>"

2. READ ISSUE COMMENTS (MANDATORY)

ALWAYS read comments — they contain valuable insights:

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

# Or via API for structured data
gh api repos/maslennikov-ig/BuhBot/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:

3. SEARCH SIMILAR PROBLEMS FIRST (MANDATORY)

Before fixing ANY issue, search BOTH sources:

3a. Search in Beads (closed tasks)

bd search "<keyword>" --type=bug --status=closed
bd search "<keyword>" --type=task --status=closed

3b. Search in GitHub (closed issues)

gh issue list --state closed --search "<keyword>"
gh issue view <number>

3c. 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 buh-xxx / gh-NN. Same fix applied.

4. CONTEXT7 IS MANDATORY

ALWAYS query documentation before implementing any fix involving external libraries:

mcp__context7__resolve-library-id → mcp__context7__query-docs

When to use:

• React/Next.js patterns
• Supabase queries
• BullMQ job handling
• Telegraf bot patterns
• Prisma ORM patterns
• tRPC router/middleware
• Any external library involved in the fix

How to use (2-step):

1. mcp__context7__resolve-library-id with library name (e.g., "telegraf", "prisma")
2. mcp__context7__query-docs with resolved ID and specific topic (e.g., "middleware", "transactions")

5. TASK COMPLEXITY ROUTING

Subagent selection:

6. BUG FIXING PRINCIPLES

This is PRODUCTION. Every bug matters.

• 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
• 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 42 43 44 — process specific issues
• /process-issues --dry-run — analyze and prioritize only, don't fix

Workflow

Phase 1: FETCH — Collect Open Issues

# Get all open issues with full metadata
gh issue list --state open --json number,title,labels,body,createdAt,comments --limit 50

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

Phase 2: ANALYZE — Deep Analysis of Each Issue

For each open issue:

1. Read issue details + comments (MANDATORY):

   gh issue view <number> --comments
   

2. Extract key information:

   • Issue type (bug/feature/enhancement)
   • Affected files/components
   • Error messages (if bug)
   • Expected vs actual behavior
   • Useful suggestions from comments

3. Search for similar resolved issues (MANDATORY):

   bd search "<keyword from issue>"
   gh issue list --state closed --search "<keyword>"
   

4. Identify cross-issue relationships:

   • Does fixing issue A require issue B to be fixed first?
   • Do issues share the same root cause?
   • Do issues touch the same files (conflict potential)?

Phase 3: PRIORITIZE — Score and Rank All Issues

For each issue, calculate a priority score using the scoring matrix:

Scoring Matrix

Severity (how bad is it?):

Impact (how many users affected?):

Likelihood (how often does it happen?):

Total Score = severity + impact + likelihood (range: 0-30)

Score → Priority mapping:

GitHub Label → default severity hints:

Output: Ranked priority table (sorted by score DESC):

| Rank | Issue | Title        | Score | Sev | Imp | Lkh | Priority | Beads ID |
| ---- | ----- | ------------ | ----- | --- | --- | --- | -------- | -------- |
| 1    | #42   | Bot crashes  | 27    | 10  | 10  | 7   | P0       | buh-xxx  |
| 2    | #43   | Login broken | 24    | 7   | 10  | 7   | P1       | buh-yyy  |
| 3    | #44   | Typo in menu | 7     | 2   | 3   | 2   | P3       | buh-zzz  |

Phase 4: CREATE BEADS — Tasks with Dependency Graph

4a. Create an Epic for this processing batch:

bd create --title="Process GitHub Issues Batch $(date +%Y-%m-%d)" --type=epic --priority=2 \
  --description="Batch processing of open GitHub issues"

Save returned <epic-id>.

4b. Create a Beads task for EACH issue (sorted by priority):

bd create --title="gh-<number>: <issue_title>" \
  --type=<bug|task|feature> \
  --priority=<0-4> \
  --external-ref="gh-<number>" \
  --deps parent:<epic-id> \
  --description="GitHub Issue: #<number>
Score: <score> (sev=<s>, imp=<i>, lkh=<l>)
Root Cause: <analysis>
Solution: <proposed fix>
Files: <file list>
Similar: <buh-xxx / gh-NN if found>
Executor: <subagent-name | MAIN>"

4c. Build dependency graph between tasks:

Analyze cross-issue dependencies and set them up:

# If issue B requires issue A to be fixed first:
bd dep add <buh-B> <buh-A>

# If issues share same root cause (related, not blocking):
# Just note in description: "Related: buh-xxx"

# If issues touch same files (sequential execution required):
bd dep add <buh-later> <buh-earlier>

Dependency rules (auto-detect):

4d. Present the dependency graph to user:

## Dependency Graph

buh-aaa (#42, P0) ─blocks──→ buh-bbb (#43, P1)
buh-aaa (#42, P0) ─blocks──→ buh-ccc (#45, P2)
buh-bbb (#43, P1) ─blocks──→ buh-ddd (#44, P3)
buh-eee (#46, P2) ── independent ──

### Execution Order (topological sort by priority):

1. buh-aaa (#42) — P0, no blockers
2. buh-eee (#46) — P2, no blockers [PARALLEL with #1]
3. buh-bbb (#43) — P1, after buh-aaa
4. buh-ccc (#45) — P2, after buh-aaa [PARALLEL with #3]
5. buh-ddd (#44) — P3, after buh-bbb

Phase 5: EXECUTE — Auto-Fix by Priority Order

Execution follows topological sort: respect dependencies, then sort by priority within unblocked tasks.

For EACH task in execution order:

5a. Claim task

bd update <task_id> --status=in_progress

5b. Query Context7 (MANDATORY for any library-related fix)

mcp__context7__resolve-library-id → mcp__context7__query-docs

5c. Gather full context

• Read ALL files that will be modified
• Search for related patterns in codebase
• Check recent commits in affected files
• Review library docs via Context7

5d. Execute fix

Subagent delegation template:

Task: Fix GitHub Issue #<number>
Issue: <title>
Root Cause: <analysis>
Solution: <proposed fix>
Files to modify:
- <path1>: <what to change>
- <path2>: <what to change>
Context7 docs: <relevant docs fetched>
Similar fix reference: <buh-xxx if applicable>
Validation: Run `npm run type-check` after changes

5e. Verify fix

npm run type-check
npm run build

• Read ALL modified files to verify correctness
• If verification fails: re-delegate with error details
• Accept/reject loop until fix passes

5f. Commit fix

Use /push patch with conventional commit message:

# Commit message format:
fix(scope): <description> (gh-<number>)
# or
feat(scope): <description> (gh-<number>)

5g. Close issue and task

# Close GitHub Issue
gh issue close <number> --comment "Fixed in commit <sha>

**Solution:**
<description of fix>

**Root cause:**
<root cause analysis>

Beads task: <task_id>"

# Close Beads task
bd close <task_id> --reason="Fixed: <description>"

5h. Move to next task

bd ready   # Check what's unblocked now

Proceed to next unblocked task by priority.

Phase 6: REPORT — Summary

## Issues Processing Complete

### Priority Score Summary

| Rank | Issue | Title | Score | Priority | Status | Beads | Commit |
| ---- | ----- | ----- | ----- | -------- | ------ | ----- | ------ |
| 1    | #42   | ...   | 27    | P0       | Fixed  | buh-a | abc123 |
| 2    | #43   | ...   | 24    | P1       | Fixed  | buh-b | def456 |
| 3    | #44   | ...   | 7     | P3       | Defer  | buh-c | —      |

### Dependencies Resolved

- buh-aaa → buh-bbb: Resolved (both fixed)
- buh-bbb → buh-ddd: Resolved (both fixed)

### Deferred Issues (need user input)

- #XX: <reason — Complex/needs clarification/P3+ deprioritized>

### Commits Made

- `abc123`: fix(bot): <description> (gh-42)
- `def456`: fix(auth): <description> (gh-43)

### Validation

- Type Check: PASS
- Build: PASS
- Issues Closed: N/M
- Beads Tasks Closed: N/M

Issue Categories & Subagents

Verification Checklist

Before marking ANY issue as fixed:

• Issue comments read and analyzed
• Useful suggestions considered (adopted/rejected with reason)
• Similar issues searched (Beads + GitHub)
• Priority score calculated (severity + impact + likelihood)
• Beads task exists with external-ref
• Dependencies set in Beads (blocks/blocked-by)
• Context7 queried for relevant library docs
• Root cause identified (not just symptom)
• Modified files reviewed with Read tool
• npm run type-check passes
• npm run build passes (or known pre-existing failures)
• Committed with conventional commit (gh-NN reference)
• GitHub issue closed with solution comment
• Beads task closed with reason

Quick Commands Reference

# === FETCH ===
gh issue list --state open --json number,title,labels,body,comments
gh issue view 123 --comments
gh api repos/maslennikov-ig/BuhBot/issues/123/comments --jq '.[] | {author: .user.login, body: .body}'

# === SEARCH SIMILAR ===
bd search "keyword"
gh issue list --state closed --search "keyword"

# === CREATE BEADS ===
bd create --title="gh-123: Issue title" --type=bug --priority=1 --external-ref="gh-123" --deps parent:<epic-id>
bd dep add <buh-child> <buh-parent>    # child depends on parent
bd blocked                              # show blocked tasks

# === EXECUTE ===
bd update <id> --status=in_progress
bd ready                                # what's unblocked?
bd close <id> --reason="Fixed: ..."

# === CLOSE GITHUB ===
gh issue close 123 --comment "Fixed in commit abc123"
gh issue comment 123 --body "Analysis: ..."

# === CONTEXT7 ===
# Step 1: resolve library ID
mcp__context7__resolve-library-id (e.g., "telegraf", "prisma", "next.js")
# Step 2: query docs
mcp__context7__query-docs (resolved ID + topic)

Reference Docs

• CLAUDE.md: Main orchestration rules
• Beads Guide: .claude/docs/beads-quickstart.md
• Priority Scoring: .claude/skills/calculate-priority-score/SKILL.md