# Issue Fixer > Use when the user wants to fix a GitHub issue, contribute to open-source, find fixable issues in a repo/organization/domain, create a pull request, or follow up on an already-open PR. Triggers: "fix issue", "修issue", "帮我去github找issue修", "find issues in ", "搜索<组织>的issue", "提PR", "追踪PR", "跟进PR状态", "contribute to open-source", a GitHub issue or PR URL, or any request about finding bugs to fix in external repos — even without naming this skill. - Skill: `re2zero/issue-fixer` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add re2zero/issue-fixer` - Raw SKILL.md: https://api.skillmd.com/api/skills/re2zero/issue-fixer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: re2zero (https://skillmd.com/u/re2zero) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/re2zero/issue-fixer --- # Issue Fixer ## Overview Automates the full open-source contribution lifecycle: **fix** a known issue, **discover** fixable issues in a repo/org/domain, and **track** a submitted PR until it is clean and mergeable. Core principles: minimal change, follow the project's own conventions, verify before pushing, never merge (user's call). **The three words are the three entry modes.** Decide the mode first, then run the matching workflow. Never skip to code before the target is settled. ## When to Use ```mermaid flowchart TD A["用户输入"] --> P1{"含 PR URL
(/pull/N)?"} P1 -->|yes| C1["Track Workflow C
监控修正回复"] P1 -->|no| P2{"含 issue URL、owner/repo#N
或裸 owner/repo?"} P2 -->|yes| C2["Fix Workflow A
定位到具体 issue"] P2 -->|no| P3{"含 --org 或提到组织?"} P3 -->|yes| C3["Discover Workflow B
--org 组织扫描"] P3 -->|no| P4{"含 --discover 或提到领域?"} P4 -->|yes| C4["Discover Workflow B
--discover 领域发现"] P4 -->|no| P5{"含 --track 或提到
追踪已有 PR?"} P5 -->|yes| C5["Track Workflow C
监控修正回复"] P5 -->|no| J["交互式
询问目标后进入对应流程"] ``` ## Input Modes | Input | Mode | Workflow | |-------|------|----------| | `owner/repo` | Target repo — find & fix an issue in it | A | | `owner/repo#42` / issue URL | Target issue — fix this exact issue | A | | `https://github.com/.../pull/N` | Target PR — track it to completion | C | | `--org ` | Scan an org's repos, pick an issue, fix it | B | | `--discover ` | Discover repos by domain (linux, cli, systems…), then fix | B | | `--track ` (number or URL) | Monitor an existing PR: CI, reviews, fix & reply | C | | (none) | Interactive — ask, then route to A/B/C | A/B/C | ## Preflight (all modes) Fail early, report the blocker, stop: ```bash gh auth status # GitHub CLI authenticated git --version # Git available ``` Refuse to work directly on `main`. Read repo instruction files (`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`) before touching code. --- ## Workflow A: Fix ### A1. Issue discovery (repo mode) For `owner/repo`, find candidates in this order until ≥3: 1. Labeled: `gh search issues --repo=$REPO --label="good first issue" --state=open` 2. Unlabeled: `gh search issues --repo=$REPO --state=open --no-assignee --sort=updated` 3. Cross-label: try `help wanted`, `beginner friendly`, `documentation`, `enhancement` Keep issues passing ALL: no assignee, not locked, updated ≤90d, body ≥50 chars, not a meta issue (track/epic), not already PR'd. Present as a numbered table and let the user pick (autonomous only in `--discover`/`--org` flows). For a specific `owner/repo#N` or URL: skip discovery, go straight to A2. ### A2. Difficulty analysis Score 4 dimensions (scope / familiarity / testability / risk), each 1-3. Total 4-12: **4-6 Easy → proceed; 7-8 Moderate → confirm with user; 9-12 Hard → skip with explanation**. Escalate to at least Moderate when the issue involves security, DB migrations, CI config, >15 files, or ambiguous root cause. Full rubric in `references/difficulty-analysis.md`. ### A3. Fork & clone Check permission: `gh repo view $REPO --json viewerPermission`. `READ` → fork first (reuse existing fork if present), set `upstream` remote; else clone directly. Create an isolated worktree: ```bash git worktree add ".worktrees/issue-$N" -b "$BRANCH" "$BASE_BRANCH" # BASE = upstream default branch ``` Branch name: `fix/issue-$N-`. Put worktrees **outside the repo** (e.g. `$TMPDIR/issue-fixer/$N`) or add the directory to `.gitignore` first — an in-repo `.worktrees/` dir shows up as untracked noise in every `git status` of the main clone. ### A4. Analyze & implement 1. Read the issue body + all comments; trace root cause, find minimal change. 2. Do NOT refactor adjacent code or add features beyond the issue. 3. Follow project style; start from any file the issue names. 4. **Tests are non-negotiable**: repro steps → test; existing suite → follow its pattern; no framework → concrete manual verification. ### A5. Quality gate Run the project's own checks before pushing. Detection order: 1. Repo instruction files (CLAUDE.md/AGENTS.md/CONTRIBUTING.md) → documented command 2. Node lockfiles (`bun.lock`/`pnpm-lock.yaml`/`yarn.lock`/`package-lock.json`) → `package.json` scripts 3. Ecosystem: `make check` · `cargo check && clippy && test` · `go vet && go test` · `cmake --build && ctest` · `ruff check && pytest` 4. Fallback: ask the user. Any failure → fix the root cause as a separate conventional commit, re-run until green. Never suppress errors (`as any`, `@ts-ignore`) or skip failing tests. ### A6. Push & PR Before creating the PR, analyze 5-10 recently merged PRs and build a convention profile (title format, body structure, commit style, branch naming, DCO sign-off) — see `references/pr-convention-analyzer.md`. ```bash git add -A && git commit -s # -s only if DCO required git push -u origin "$BRANCH" # never force-push gh pr create --draft --title "fix(): " --body-file /tmp/pr-body.md ``` PR body must reference the issue (`Fixes #N`) and include Summary / Changes / Test Plan. **Always draft PR** unless the user explicitly consents to ready-to-merge. Then hand off to **Workflow C** for the follow-up loop. --- ## Workflow B: Discover Find a repo, then enter Workflow A at A1/A2. ### B1. Domain discovery (`--discover `) Domain templates (topic/language/star thresholds) and `gh search repos` recipes are in `references/repo-discovery.md` (linux, systems, cli, networking, security, devtools…). Round-based broadening: exact match → relax language → drop topic. ### B2. Organization discovery (`--org `) Full recipe in `references/repo-discovery.md` § Organization scanning: 1. `gh repo list $ORG` → filter by stars/open issues/language → shortlist 2. Per shortlisted repo: `gh search issues` with good-first-issue labels 3. Merge, filter (A1 criteria), score difficulty (A2), pick easiest 4. Continue into Workflow A (fork → fix → quality gate → PR → C) ### B3. Candidate presentation Present a numbered table (repo / stars / open issues / activity). In autonomous mode pick the top candidate with an **Easy** score. If nothing fixable, broaden and repeat — do not settle for a Hard issue. --- ## Workflow C: Track Monitor a PR until it is clean: handle reviews, fix CI failures, reply on every thread, keep the branch synced. Full loop (state checks, comment fetching, classification, reply format, recheck ordering, completion criteria) in `references/pr-tracking.md`. **REQUIRED BACKGROUND:** the classification and reply policy in `references/pr-tracking.md` mirrors `review-pr-comments` — if that skill is installed, load it instead of re-deriving the policy. ### C0. Resolve the PR `gh pr view --json number,state,headRefOid,mergeable,isDraft`. If in a repo, a bare number works; otherwise the URL carries owner/repo. ### C1. Loop until done For each round: **reviewer-first** — fetch comments/reviews/unresolved threads first; only when the review surface is quiet, check CI. **Filter noise**: only AI-bot/maintainer reviews and maintainer comments are actionable; other user comments and automation notices are read-only (details in `references/pr-tracking.md` § Noise filtering). 1. Classify feedback → Fix / False Positive / Out of Scope / Needs Discussion / Informational 2. Fix actionable items in smallest changes; run quality gate (A5); commit; push 3. Reply on **each original thread** (`in_reply_to=` for review comments; quote permalink for issue comments); one reply per finding 4. CI failed → read logs, fix root cause, push 5. `git fetch upstream && git merge upstream/main` to stay synced 6. Max 3 CI-fix rounds, then escalate to user ### C2. Done condition PR ready when, for **two consecutive clean rounds**: no new actionable comments, no unresolved threads, all CI passing, branch synced, GitHub reports mergeable. Report the final state (comments fixed/dismissed, CI, merge-ready, remaining threads). Do NOT merge. --- ## Common Mistakes | Mistake | Fix | |---------|-----| | Reading `description` and skipping the workflow | Mode first → matching workflow; each mode has a distinct loop | | Settling for a Hard issue in autonomous mode | Difficulty score gates every pick (A2) | | Pushing without the project's own quality gate | A5 detection order; gate before every push | | One summary reply instead of per-thread replies | Hard rule: every actionable finding gets its own reply | | Waiting on CI while reviews are pending | Reviewer-first invariant (C1) | | Working on `main` | Always an isolated worktree + feature branch | | Forgetting `Fixes #N` or DCO sign-off | Convention profile from merged PRs (A6) | | Over-engineering the fix | Minimal change; refactor/features are separate issues | ## Safety Guardrails - **Never commit to `main`**; never force-push (use `--force-with-lease` only if explicitly asked) - **Never delete tests** — deleting failing tests is forbidden - **Max 15 files changed** — beyond that, stop and ask - **Security / DB migrations → guided mode** — always require human oversight - **Draft PR by default** — never create a ready-to-merge PR without explicit consent - **Respect CLA/DCO** — inform the user before submitting if a CLA is required - **No AI identification by default** — no `Co-Authored-By`, `Assisted-by`, or AI mentions in commits/PRs/output unless the **project explicitly requires disclosure**; then follow the project's disclosure format exactly (`references/pr-convention-analyzer.md` § E)