Fix Issues

Batch Issue Fixing Pipeline

Arguments: $ARGUMENTS — optional space-separated issue numbers to limit the batch. Empty means all open issues.

This skill encodes the full process: triage -> parallel fixes in isolated worktrees -> merge into develop -> release -> final review -> publish. Follow the phases in order. All gh commands run from the repo root (no --repo flag needed).

Phase 0 — Preflight

1. git fetch origin and confirm the working tree is clean (git status --short). If dirty, stop and ask the user.
2. Compare branches: git rev-list --left-right --count origin/main...origin/develop.
   • If develop is strictly behind main (0 unique commits), fast-forward it: git push origin origin/main:develop.
   • If develop has unique commits, ask the user how to proceed before branching anything.
3. All fix branches are created from origin/develop.

Phase 1 — Triage

1. List issues: gh issue list --state open --limit 100 --json number,title,labels.
2. Read EVERY issue in scope with comments: gh issue view <n> --comments. Comments often contain the real root cause or a maintainer-agreed approach.
3. Build a summary table (number, type bug/feature, one-line problem). Explicitly check for duplicates and overlapping fixes.
4. Ask the user (AskUserQuestion) before starting work:
   • Scope: which issues go into this batch (call out breaking changes and pure feature requests separately).
   • Whether to auto-merge fix PRs into develop or leave them open for manual review.
   • Anything that looks external/not-a-bug (e.g. Docker Hub rate limits): propose fix / message-only / skip-and-close options.
5. Decide the version bump now (semver table in CLAUDE.md) so the release phase is mechanical. The user may override.

Phase 2 — Parallel fixes (one worktree + one agent per issue)

1. Create worktrees as siblings of the repo:

   git worktree add ../<repo-name>-worktrees/issue-<n> -b fix/issue-<n>-<slug> origin/develop
   

   Use fix/ for bugs, feat/ for features (feat! commit prefix for breaking changes).
2. Launch one background agent per issue, all in parallel. Each agent prompt MUST include:
   • Work EXCLUSIVELY in its worktree path; never touch the main checkout.
   • Work fully autonomously; never wait for user input.
   • Step 1: read the issue with gh issue view <n> --comments and the worktree's CLAUDE.md.
   • Step 2: invoke the Skill tool with feature-dev:feature-dev to implement. Skip interactive steps; prefer the minimal robust fix.
   • Step 3: commit with a conventional-commit message.
   • Step 4: invoke the Skill tool with pr-review-toolkit:review-pr on the diff origin/develop...HEAD. Fix ALL critical and important findings; ignore nitpicks. Commit fixes.
   • Step 5: git push -u origin <branch> and open a PR to develop with gh pr create --base develop. Body in plain English: summary, what changed, verification, and the line Fixes #<n>.
   • Constraints: do NOT modify CHANGELOG.md or VERSION (prevents 7-way merge conflicts; release handles both). Verification: bash -n on every changed script, cp .env.example .env (gitignored, delete after) + docker compose -p localai config --quiet, node --check welcome/app.js if touched. Docker CLI may not be on PATH — try /usr/local/bin/docker.
   • Known facts from the codebase report (file, line numbers, verified behavior) — give each agent everything already learned during triage.
   • Push the agent to verify root causes upstream (WebFetch the upstream repo/Dockerfile/entrypoint) rather than trusting the issue's proposed fix. Issues regularly misdiagnose (wrong mount path vs stale volume; missing tool vs wrong endpoint).

Phase 3 — Merge into develop

As each agent finishes (do not wait for all):

1. Read its PR diff (gh pr diff <pr>) and sanity-check it yourself — minimal, on-topic, matches the report.
2. Check mergeability: gh pr view <pr> --json mergeable -q .mergeable. UNKNOWN right after another merge is normal — poll a few times with short sleeps.
3. Merge with a merge commit (repo convention): gh pr merge <pr> --merge. Resolve conflicts manually if CONFLICTING.
4. After ALL merges, validate the combined develop: full bash -n list from CLAUDE.md "Testing Changes", python3 -m py_compile start_services.py, node --check welcome/app.js, compose config with a temp .env, and a repo-wide grep for anything a removal-type fix should have fully cleaned.

Phase 4 — Release on develop

1. In a develop worktree: set VERSION, add the CHANGELOG.md section ## [X.Y.Z] - <today> under [Unreleased] with Added/Changed/Removed/Fixed entries in the file's established style (one bold service name + detailed prose + (#issue) per entry). Match the file's actual conventions, not assumed ones (e.g. this changelog has never used compare links at the bottom).
2. Commit (chore: release X.Y.Z), push develop.
3. Open the release PR: gh pr create --base main --head develop --title "Release X.Y.Z" with a per-issue summary and Fixes #<n> lines for every issue in the batch (auto-close only fires when the merge reaches main, so these lines belong HERE, not only in the fix PRs).

Phase 5 — Final integration review

The per-fix reviews cannot see interactions between fixes, so review the aggregate diff origin/main...origin/develop:

1. Launch review agents in parallel (read-only, on the main checkout): pr-review-toolkit:code-reviewer, pr-review-toolkit:comment-analyzer, pr-review-toolkit:silent-failure-hunter. Skip test/type analyzers (no test suite, no typed code here).
2. Point them explicitly at cross-fix interactions (e.g. does fix A's preserve/cleanup logic interact with fix B's removals? Is the update-flow ordering in apply_update.sh still correct?), CHANGELOG factual accuracy, and paths other than make update (git pull + make restart is a documented user path — new secrets are NOT generated there).
3. Fix all critical and important findings (plus cheap correctness suggestions) directly on develop, verify (bash -n, targeted roundtrip tests under bash -c, compose config), push. The PR updates automatically.
4. If an external reviewer bot (e.g. CodeRabbit) commented on the PR, fetch its findings (gh api repos/{owner}/{repo}/pulls/<pr>/comments), verify each against the code, fix the valid ones, and reply to the inline comments with the fix commit.
5. Present the aggregated report (Critical / Important / Suggestions / deliberately skipped) and leave the release PR open for the user unless they said to merge it.

Phase 6 — Publish (only on explicit user go-ahead)

1. gh pr merge <release-pr> --merge, then tag the merge commit: git tag vX.Y.Z <sha> && git push origin vX.Y.Z (v-prefix per existing tags).
2. gh release create vX.Y.Z --title "vX.Y.Z" — match the format of previous releases (gh release view <prev> first): changelog sections, an ## Upgrade block with make update plus per-service migration notes, and a **Full Changelog** compare link.
3. Verify the issues auto-closed, then comment on each: fixed in release (link), one-line what changed, any caveat specific to that issue, and "please update with make update".

Cleanup

Remove worktrees and branches once merged:

git worktree remove --force ../<repo-name>-worktrees/issue-<n>
git branch -D <branch> && git push origin --delete <branch>

Hard-won rules (violating these caused real problems)

• Fix agents must never edit CHANGELOG.md/VERSION — the release commit owns them.
• Poll mergeable when it reports UNKNOWN; GitHub recomputes it after every merge to the base.
• Fixes #N in a PR targeting develop closes nothing — repeat the keywords in the release PR to main.
• New secrets in 03_generate_secrets.sh are only generated by make update/make install; every fix that adds one needs a doctor.sh check and, where it matters, a restart.sh warning for the git pull + make restart path.
• When a fix removes a service, grep the whole repo for its name at the end; expect leftovers in GOST_NO_PROXY, wizard, welcome page, doctor, final report, update_preview, Caddyfile, docs, and add a one-time migration (see cleanup_removed_* functions in scripts/utils.sh).
• Never log success after a suppressed command (|| true); branch the message on the actual result.