End-to-end playbook for shipping high-quality pull requests to open-source projects you don't maintain — discovery, CONTRIBUTING compliance, PR-size check, minimal-diff implementation, PR description with AI-assisted disclosure, conflict resolution, and post-submission maintainer interaction. Use wh

GitHub Contributor A phase based playbook for shipping pull requests that maintainers actually want to merge. The skill is structured around the real PR lifecycle — discovery → implementation → quality gates → description → post submission — because each phase has its own failure modes and the most common mistake is doing the right thing at the wrong phase (e.g., writing the perfect description for a PR that's 10× too large). Phase 0 — When to use this skill Use this skill when all of these are true: You are contributing to a repo you do not maintain (the maintainer can close your PR without explanation). The work touches one or more of: source code, tests, docs, build config. You want the PR merged, not just submitted. Do not use this for: your own repos, internal team PRs with shared context, hot fix branches where a maintainer is waiting on you, or trivial single line changes (one comment is enough). Phase 1 — Pre PR Discovery The most common reason PRs get closed is a mismatch between what the contributor assumes is acceptable and what the maintainer has already written down. Solve this before writing code. Step 1.1 — Read CONTRIBUTING.md as a hard contract CONTRIBUTING.md is not style advice. Treat every numbered rule as a precondition for merge. Pay special attention to: AI assisted contribution clauses. Many projects added these in 2024 2026 after the AI PR wave. Typical phrasing: "AI generated PRs without prior discussion may be closed", "you must be able to explain every line", "one issue, one PR". If this clause exists, you owe the project explicit disclosure (see Phase 4) and you must keep the PR small. Issue first rules. Some projects require a feature request issue to exist before any feature PR is opened. Per language test commands. If CONTRIBUTING.md says pnpm test:unit && cargo test , those are the commands you run, not whatever your IDE prefers. If CONTRIBUTING.md is missing, that itself is a red flag — see [ references/project evaluation.md ](references/project evaluation.md). Step 1.2 — Sanity check your PR size against the project's baseline A "small PR" is relative. Before opening a PR, run: This tells you the project's actual merged PR size distribution. If your PR is 5–10× larger than the biggest recent merge , that is a red signal — split before submitting. See [ references/phase1 discovery.md ](references/phase1 discovery.md) for the baseline rubric and split heuristics. Step 1.3 — Write a one paragraph scope contract before coding A scope contract is a single paragraph you write to yourself before opening your editor: Goal: <one sentence . In scope: <bullet list, 3–5 items . Explicitly out of scope: <bullet list — be specific about what you will resist adding when it's tempting . Then, every time you make an edit, ask: "Is this in scope?" If you find yourself "while I'm in here…" ing, stop and revisit the contract. Scope creep is the single biggest source of close without merge — see [ references/phase2 implementation.md ](references/phase2 implementation.md) for the scope discipline section. Phase 2 — Implementation Step 2.1 — Branch off main immediately after fetching upstream Always branch from upstream main (or the project's default branch), never from your fork's main , which may be stale. Step 2.2 — Make the smallest diff that solves the problem Resist any change that is not directly required by your scope contract. In particular: Do not "while I'm here" refactor surrounding code. Do not reformat lines you didn't touch (your formatter may differ from the project's, even if both say "Prettier"). Do not rename variables for clarity unless the renaming is the fix. If a follow up improvement is genuinely valuable, file a separate issue or open a separate PR after this one is merged. Step 2.3 — Conventional Commits, one logical change per commit Use [Conventional Commits](https://www.conventionalcommits.org/): <type (<scope ): <description where type is feat fix docs refactor test chore ci perf . Each commit should be reviewable on its own. When a review prompts a fix, use git commit fixup=<sha and squash with git c sequence.editor=: rebase i autosquash origin/main before pushing — see [ references/phase2 implementation.md ](references/phase2 implementation.md) for the full fixup workflow. Phase 3 — Quality Gates Maintainers' trust is built by evidence, not by claims. The point of this phase is to produce evidence you can paste into the PR. Step 3.1 — Establish the project's required checks Read CONTRIBUTING.md and the current CI workflow for the required commands and platform matrix. Reuse successful checks on the exact same content when their inputs remain applicable; otherwise run the missing or affected checks. Typical examples (use what your project specifies): For a failure, compare the same command against the immutable current base in an isolated worktree before attributing it to the PR. Preserve failed results and distinguish a regression from an existing defect or environment blockage; never stop another session's service to make a test pass. Complete the repository's required checks before claiming merge readiness. Step 3.2 — For GUI / desktop apps: run real end to end with isolation For Tauri/Electron/Cocoa apps you almost certainly cannot use pnpm dev directly without contaminating your real installation. The pattern is isolate the data directory first, then run the real binary : 1. Find the project's test isolation hook (often XXX TEST HOME , XXX DATA DIR , or a config flag in config.rs / paths.go ). 2. Point it at /tmp/<app name e2e/ before launching. 3. Trigger the feature through whatever real surface the user would (URL scheme, CLI arg, deeplink). 4. Verify by reading the actual persisted state (SQLite, JSON files), not just by visual inspection. 5. Capture screenshots of the GUI for the PR description. The full isolation recipe, including how to trigger deeplinks via Tauri's single instance forward without touching macOS LaunchServices, is in [ references/phase3 quality gates and e2e.md ](references/phase3 quality gates and e2e.md). Step 3.3 — Self audit: did you actually do what you're about to claim? For changes with downstream behavior, use [behavioral impact review](../github review pr/references/behavioral impact review.md) to select preservation tests before accepting a local pass, and again after a review led repair. Resolve that reference through the installed github review pr Skill when contributing outside this marketplace; if it is unavailable, require actual consumer checks against the original result/preservation contract and report the missing reference. This does not invoke an independent review or grant maintainer authority. Before writing the PR description, list every "I tested…" / "I verified…" / "I ran…" statement you intend to make. For each one, ask: "What's my evidence?" If the answer is "I think I did" or "it should work", you have not actually done it. Write only what you can defend. This rule prevents the most damaging trust failure: a maintainer running your "tested" command and finding it doesn't work. When the user explicitly asks for an independent maintainer style evaluation of their own contribution, invoke github review pr:github review pr for its read only review method. Give fresh context reviewers the original issue/review discussion and immutable head/base objects. Keep the requester in the author role: this produces a recommendation, not a formal approval or permission to merge. Continue repairs through this contributor workflow only within existing authorization. Ordinary self audits do not trigger it. Step 3.4 — Push time verification Local tests passing is not the finish line. Before you call the PR merge ready, run the push time checklist: 1. Visibility check — confirm the target repo is actually public/private as you assume: 2. Security hooks — if pre push fails, fix the rule or the content; do not no verify . 3. Push succeeds — if it fails with 503/auth errors, check git config global get regexp url for stale URL rewrites. 4. Mergeability check — git push succeeding does not mean GitHub can merge: Full details (URL rewrites, PII hook false positives, force with lease caveats) are in [ references/push time gotchas.md ](references/push time gotchas.md). Phase 4 — PR Description Writing A great PR description does three jobs: (1) lets the maintainer decide in 30 seconds whether to merge, (2) gives reviewers everything they need to verify without DM'ing you, (3) creates a written record that survives team turnover. Step 4.1 — Structure Use this skeleton. Detailed templates and a test coverage matrix example are in [ references/phase4 pr description.md ](references/phase4 pr description.md) and [ references/communication templates.md ](references/communication templates.md). Step 4.2 — Test coverage matrix (for non trivial changes) When you've added more than 2 tests, present them as a table mapping each test to the behavior it locks in. This makes review much faster than reading test code: Step 4.3 — Screenshots without polluting the repo gh CLI does not support image attachments to PRs (the underlying upload API at uploads.github.com is browser only and rejects PAT tokens). Three workable approaches: 1. Preferred — let the user drag images in the GitHub web UI. Leave clearly marked placeholders in your PR body draft (e.g. [SCREENSHOT 1 PLACEHOLDER] ). When the user edits the PR on github.com, they drag images into the markdown, GitHub uploads them to user images.githubusercontent.com , and the placeholders are replaced. Zero pollution. 2. Fallback — orphan branch on your fork. Create an orphan branch (e.g. named assets pr N screenshots ), commit images, reference them via raw.githubusercontent.com . Pollutes your fork but not the PR diff. 3. Last resort — third party image host. Persistence + privacy are unclear; avoid for anything sensitive. Step 4.4 — AI Assisted Disclosure (when CONTRIBUTING.md or maintainer norms call for it) If the project's CONTRIBUTING.md mentions AI assisted PRs, or the maintainer has commented skeptically about AI output on past PRs, add a short disclosure at the bottom of the PR body. Be specific about what you did, not vague reassurances. The disclosure is not magic — it doesn't excuse a bad PR. But missing it on a project that asks for it is an instant trust hit. Phase 5 — Post Submission Step 5.1 — Respond to automated bot reviews explicitly Modern projects use Codex, Claude bot, CodeRabbit, etc. for first pass review. Their comments appear as review comments on specific lines , not as PR level comments. Reply to each finding directly (so maintainers see the resolution next to the finding), citing the commit hash and the function/test that resolves it: <finding comment id is the numeric ID from the comment's URL ( discussion rXXXXXXXX ). Full bot reply workflow in [ references/phase5 post submission.md ](references/phase5 post submission.md). Step 5.2 — Rebase against upstream main without losing review history When upstream main advances and your PR conflicts: Use force with lease , never plain force . The lease variant aborts if someone else (or a bot) pushed to your branch in between, which prevents you from silently destroying review threads. If you applied a small post review cleanup (a fixup commit), squash it into the relevant commit with autosquash so the merged history stays clean. See [ references/phase2 implementation.md ](references/phase2 implementation.md) for the full sequence. Step 5.3 — When sub agent / counter review surfaces "findings", filter before responding If you run a counter review agent (or a maintainer's bot floods you with 20+ findings), don't paste

github-contributor