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

flowchart TD
    A["用户输入"] --> P1{"含 PR URL<br/>(/pull/N)?"}
    P1 -->|yes| C1["Track Workflow C<br/>监控修正回复"]
    P1 -->|no| P2{"含 issue URL、owner/repo#N<br/>或裸 owner/repo?"}
    P2 -->|yes| C2["Fix Workflow A<br/>定位到具体 issue"]
    P2 -->|no| P3{"含 --org 或提到组织?"}
    P3 -->|yes| C3["Discover Workflow B<br/>--org 组织扫描"]
    P3 -->|no| P4{"含 --discover 或提到领域?"}
    P4 -->|yes| C4["Discover Workflow B<br/>--discover 领域发现"]
    P4 -->|no| P5{"含 --track 或提到<br/>追踪已有 PR?"}
    P5 -->|yes| C5["Track Workflow C<br/>监控修正回复"]
    P5 -->|no| J["交互式<br/>询问目标后进入对应流程"]

Input Modes

Preflight (all modes)

Fail early, report the blocker, stop:

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:

git worktree add ".worktrees/issue-$N" -b "$BRANCH" "$BASE_BRANCH"   # BASE = upstream default branch

Branch name: fix/issue-$N-<slug>.

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.

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(<scope>): <desc>" --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>)

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 <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 <number-or-URL> --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

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)