GitHub Contributor

# 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:

```bash
gh pr list --repo <owner>/<repo> --state merged --limit 10 \
  --json number,title,author,additions,deletions \
  --jq '.[] | "#\(.number) +\(.additions)/-\(.deletions): \(.title)"'
```

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