OmniRoute/.agents/skills/resolve-issues-cc/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
resolve-issues-cc	Fetch all open GitHub issues, analyze bugs, resolve up to 30 per batch via per-issue worktrees + PRs into the release branch, triage the rest, wait for user validation	Bash, Read, Edit, Write, Grep, Glob, WebFetch, WebSearch, AskUserQuestion, Agent

/resolve-issues — Automated Issue Resolution Workflow

Overview

This workflow fetches all open issues from the project's GitHub repository, classifies them, analyzes bugs, proposes a resolution plan, waits for user validation, and ONLY THEN implements fixes. The current release/vX.Y.Z branch is the integration target — each individual fix is implemented on its own short-lived fix/<issue>-<short> branch inside its own git worktree, merged into the release branch via PR, then the worktree and local branch are deleted. The release branch is later merged to main via /generate-release.

BRANCH RULE: The current release/vX.Y.Z branch is the integration target. Each fix MUST live on its own fix/<ISSUE>-<short> branch cut from the release branch, inside its own worktree under .worktrees/. After the per-issue PR is merged into the release branch, the worktree and local branch are deleted. Never commit fixes directly to the release branch. If no release branch exists yet, create one first using /generate-release Phase 1 steps 1–5.

⛔ PR PROHIBITION: If a fix is associated with a contributor's PR, you MUST merge their PR — NEVER close it and re-implement the fix yourself. See /review-prs workflow for the full policy. The gh pr close command is FORBIDDEN unless the repository owner explicitly requests it.

🌐 REPLY LANGUAGE: All comments posted to issues (close messages, RESPOND comments, PR descriptions visible to the reporter) MUST match the reporter's language. When in doubt, default to English. The reporter's language is detected from the issue body and prior comments by that author.

Steps

1. Identify the GitHub Repository

// turbo

• Run: git -C <project_root> remote get-url origin to extract the owner/repo
• Parse the owner and repo name from the URL

2. Ensure Release Branch Exists

// turbo

Before doing any work, ensure a release/vX.Y.Z branch exists. If you are currently on main, create one:

git branch --show-current

# If on main, determine next version and create the release branch
VERSION=$(node -p "require('./package.json').version")
NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=999?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
git checkout -b release/v$NEXT
npm version patch --no-git-tag-version
npm install

Threshold: patches climb to .999 before rolling. Example: 3.4.999 → 3.5.0.

If already on a release/vX.Y.Z branch, continue working there.

3. Fetch All Open Issues (cap 30 per batch)

// turbo-all

⚠️ CRITICAL: The JSON output of gh issue list can be truncated by the tool, silently hiding issues. Use the two-step approach below.

Step 3a — Get Issue numbers only (small output, never truncated):

• Run: gh issue list --repo <owner>/<repo> --state open --limit 500 --json number --jq '.[].number'
• Count them and remember the total.

Step 3b — Fetch full metadata for each Issue (parallel, validated against 3a):

• For each issue number from step 3a, run: gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,url
• Batch in parallel (8–12 concurrent calls). After completion, assert fetched_count == count_from_3a; if mismatch, retry the missing IDs.
• Sort by oldest first (FIFO).

Step 3c — Cap at 30 per run:

• If more than 30 open issues qualify as bugs after step 4, ask the user (via AskUserQuestion) which subset of up to 30 to handle now. The remainder is deferred to the next run.

4. Classify Each Issue

For each issue, determine its type:

• Bug — Has bug label, or body contains error messages, stack traces, "doesn't work", "broken", "crash", "error"
• Feature Request — Has enhancement/feature label, or body describes new functionality
• Question — Has question label, or is asking "how to" something
• Other — Anything else

Focus ONLY on Bugs for resolution. Feature requests and questions are skipped with a note in the final report.

4.5. PR-Linked Check (mandatory)

For every bug, query linked PRs:

gh issue view <NUMBER> --repo <owner>/<repo> --json closedByPullRequestsReferences,body

If the issue is referenced by an open contributor PR (or the body links to one), do NOT plan a self-implemented fix. Mark the issue as 🤝 PR-LINKED — redirect to /review-prs in the report and stop deeper analysis for it. NEVER close the contributor PR.

5. Deep-Read Each Bug Issue (One-by-One Analysis)

Read each bug issue thoroughly, one at a time. Each issue gets focused attention.

5a. Understand the Problem

1. Read the entire body — Description, Steps to Reproduce, Expected/Actual Behavior, Error Logs, Screenshots
2. Read ALL comments — bot triage (Kilo, etc.) and owner/community responses. Look for:
   • Someone already responded with a fix
   • Community member confirmed it is resolved
   • Bot duplicate flag. DO NOT blindly trust bot labels (e.g., kilo-duplicate). Re-verify independently from current source + web research.
3. Identify the claimed error — exact error message, status code, provider/model, OS, Node version.

5b. Check Information Sufficiency

Verify the issue contains:

• Clear description of the problem
• Steps to reproduce OR error logs
• Provider/model/version information
• Expected vs actual behavior

If ANY item is missing → auto-classify as 📝 RESPOND — Needs Info and skip 5d. Do not attempt root-cause analysis on under-specified issues.

5c. Determine Issue Disposition

Disposition	When to Apply	Action
✅ CLOSE — Already Fixed	Owner responded with fix + no user follow-up, OR community confirmed fix	Close with comment citing which version fixed it
✅ CLOSE — Duplicate	You have independently verified the issue is a duplicate (do NOT rely solely on bot flags) + user provides no new info	Close referencing the original issue
✅ CLOSE — Stale	We requested logs/info > 7 days ago with no reply	Close thanking the user, invite to reopen if needed
📝 RESPOND — Needs Info	Issue is real but missing critical reproduction details (also triggered by 5b)	Comment asking for specifics per /issue-triage
📝 RESPOND — User Config	Error is caused by unsupported env (Node version, wrong model path, missing API enablement)	Comment explaining the user-side fix
🤝 PR-LINKED	An open contributor PR already targets this issue (from step 4.5)	Redirect to /review-prs; do not re-implement
🔧 FIX — Code Change	Root cause is confirmed in the codebase	Research, propose solution in report, wait for approval

5d. For "FIX — Code Change" Issues

Before coding, perform deep source analysis:

1. Search the codebase — grep/Grep for error strings, function names, affected files
2. Search the web — upstream API changes, SDK updates, breaking changes
3. Read the full source file — don't rely on grep snippets
4. Verify the root cause is in our code, not user misconfiguration
5. Formulate a proposed solution — exact files/lines/logic
6. Create an Implementation Plan file at _tasks/fixes-vX.Y.Z/<ISSUE>-<short-description>.plan.md (vX.Y.Z = current release branch version). Create the directory first: mkdir -p _tasks/fixes-vX.Y.Z. The plan contains: Overview, Reproduction Steps, Regression Test Outline, Implementation Steps (files/changes), Rollout Notes.
7. DO NOT modify the codebase yet — wait for user approval.

5e. For "RESPOND" Issues

Post a substantive comment that:

• Acknowledges the specific error reported
• Explains the likely root cause
• Provides concrete steps (version upgrade, env var fix, model path correction)
• Asks for follow-up info if needed

No generic templates. Every comment references the user's specific error and environment, and is written in the reporter's language (English default).

6. Generate Report & Wait for Validation

Present a summary report. For FIX bugs, explicitly explain the proposed solution (files to change + logic) and confirm it will land via per-issue worktree → PR → release branch after approval. Include the reporter's detected language per row so the user can verify.

Issue	Title	Status	Reply Lang	Proposed Action / Version
#N	Title	✅ Close	en	Already fixed / duplicate (explain why)
#N	Title	🔧 Propose	pt-BR	Code fix plan summary + worktree branch
#N	Title	📝 Respond	en	Guidance comment to be posted
#N	Title	❓ Needs Info	en	Triage comment to be posted
#N	Title	🤝 PR-Linked	en	Redirect to /review-prs (PR #M)
#N	Title	⏭️ Skip	—	Feature request / not a bug

⚠️ IMPORTANT: Do NOT implement code changes, commit, push, or close issues at this step. Wait for the user to review the proposed fixes and respond with OK before proceeding.

• If the user says OK → Proceed to step 7
• If the user requests changes → Adjust and re-present the report
• If the user rejects → Revert any accidental changes and stop

7. Implement Fixes via Per-Issue Worktrees + PRs (only after user approval)

For each approved FIX issue (up to 30 per batch), repeat the following sequence. Issues can be processed sequentially or in parallel (one worktree each — never two fixes in the same worktree).

7.1. Spin up an isolated worktree on a fresh fix branch

ISSUE=<NUMBER>
SHORT=<short-kebab-desc>
RELEASE_BRANCH=$(git -C <project_root> branch --show-current)   # release/vX.Y.Z
WT_DIR=".worktrees/fix-${ISSUE}-${SHORT}"
BRANCH="fix/${ISSUE}-${SHORT}"

git fetch origin "$RELEASE_BRANCH"
git worktree add "$WT_DIR" -b "$BRANCH" "origin/$RELEASE_BRANCH"
cd "$WT_DIR"

7.2. Write the regression test first (TDD)

• Author a unit/integration test that reproduces the bug. It must fail on the unfixed code. Run it and confirm the failure.
• Hard rule #8: any production change must ship with tests in the same PR. The regression test is non-negotiable.

7.3. Implement the fix

• Apply the approved plan from _tasks/fixes-vX.Y.Z/<ISSUE>-<short>.plan.md.
• Keep the diff scoped to this issue. No drive-by refactors.

7.4. Run the test suite

• npm run test:all (or the appropriate suite for the touched area; the regression test MUST be included).
• All tests must pass before commit. Also run the relevant lint / typecheck per CLAUDE.md trust-but-verify checklist.

7.5. Update CHANGELOG.md and commit (single commit, same diff)

• Add the new bug-fix entry under the current vX.Y.Z section of CHANGELOG.md.
• CHANGELOG entry + code + test go in one commit on the fix branch:

git add <changed files> CHANGELOG.md
git commit -m "fix: <description> (#${ISSUE})"

7.6. Push and open a PR into the release branch

git push -u origin "$BRANCH"
gh pr create \
  --base "$RELEASE_BRANCH" \
  --head "$BRANCH" \
  --title "fix: <description> (#${ISSUE})" \
  --body "Closes #${ISSUE}\n\n<short summary, plan link, regression test reference>"

7.7. Merge the PR into the release branch

• Wait for CI green, then merge with the project's default merge strategy.
• The PR title becomes the release-branch commit.

7.8. Clean up worktree and local branch

cd <project_root>
git worktree remove "$WT_DIR"
git branch -D "$BRANCH"

7.9. Close the issue with a localized comment

Match the reporter's language (English default). Template:

EN: Thanks for reporting! Fixed in release/vX.Y.Z (already merged into the active development branch — feel free to pull and test it now). It will ship in the next release (vX.Y.Z).

pt-BR: Obrigado pelo report! Corrigido em release/vX.Y.Z (já mergeado na branch de desenvolvimento atual — pode dar pull e testar). Vai sair na próxima release (vX.Y.Z).

gh issue close "$ISSUE" --repo <owner>/<repo> --comment "<localized message above>"

7.10. Close non-FIX dispositions

After all FIX issues are merged:

• Duplicate: close referencing the original issue (localized).
• Stale: close thanking the user and inviting reopen (localized).
• RESPOND — Needs Info / RESPOND — User Config: post the substantive comment from 5e (localized).
• PR-LINKED: leave the issue open; comment redirecting to the contributor PR if not already linked.

7.11. Hand off to release flow (optional)

If a release PR to main is desired now, run /generate-release Phase 1 steps 7–10 (tests → commit version bump → push → open PR to main → wait for user).

If NO fixes were committed, skip 7.7–7.11 and just conclude the workflow.