pr-contribution

What this skill does

# PR Contribution

**Every PR is a proposal to a stranger's codebase. Respect their time, follow their rules, prove your change deserves to
exist.**

Agent-generated PRs are rejected more often than human PRs — not because the code is wrong, but because they lack
context, violate implicit norms, and burden maintainers with unnecessary review work.

## References

- **PR descriptions** — `${CLAUDE_SKILL_DIR}/references/pr-descriptions.md` Full description anatomy:
  summary/body/metadata structure, templates, anti-patterns, scaling description depth to change size
- **Agent PR quality** — `${CLAUDE_SKILL_DIR}/references/agent-pr-quality.md` Why agent PRs get rejected: seven
  agent-only failure modes, measurable quality gaps, implicit knowledge problem, trust-building signals
- **Fork workflow** — `${CLAUDE_SKILL_DIR}/references/fork-workflow.md` Fork setup, branch discipline, upstream sync,
  pre-submission cleanup, gh CLI submission, review response protocol
- **Contribution compliance** — `${CLAUDE_SKILL_DIR}/references/contribution-compliance.md` CLAs, DCOs, project
  guideline discovery, AI contribution transparency

## Preparation Pipeline

Before writing any code or opening any PR, complete these checks. Skipping preparation is the primary cause of
rejection.

### Read the Project

- Read `CONTRIBUTING.md` — it is authoritative. Follow every instruction it contains.
- Read `README.md` for project vision, scope, and setup
- Read `CODE_OF_CONDUCT.md` if present
- Check for a PR template (`.github/pull_request_template.md`) — you must use it

### Check for Duplicates

- Search open AND closed issues for the problem you are solving
- Search open AND closed PRs for similar changes
- If a related issue exists, comment on it before starting work
- If a related PR was rejected, understand why before attempting the same change

### Understand Project Norms

- Read 3-5 recent merged PRs to learn:
  - Title conventions (imperative mood? conventional commits? ticket references?)
  - Description depth and structure
  - Commit message style
  - Review turnaround expectations
- Identify the project's code style: linter configs, `.editorconfig`, formatting tools
- Check CI configuration to understand what automated checks will run

### Verify Legal Requirements

- Determine if the project requires a CLA or DCO sign-off
- If CLA: sign it before submitting (check for CLA bot on existing PRs)
- If DCO: add `Signed-off-by` trailer to every commit (`git commit -s`)
- If contributing on behalf of an employer, verify corporate CLA coverage

### Scope the Change

- For non-trivial changes, open an issue first to discuss the approach with maintainers
- Do not solve issues labeled "good first issue" — these are reserved for humans learning the project
- One logical change per PR — never bundle unrelated fixes
- Separate refactoring from behavioral changes into distinct PRs
- Keep PRs small: 100 lines is reasonable, 1000 lines is almost always too large. Reviewers can reject a change solely
  for being too large.
- When splitting large work, use concrete strategies: split by layer (model/API/client), split by feature (vertical
  slices), or stack dependent changes as a series of PRs
- If work requires multiple PRs, state the plan in the first one
- Include related test code in the same PR as the code change — do not submit tests separately unless they are
  independent validations of pre-existing code

## PR Titles

The title is the first thing a reviewer reads — it determines whether they engage now, later, or never.

**Rules:**

- Use imperative mood: "Fix", "Add", "Remove" — not "Fixed", "Adding", "Removed"
- Describe **what** the change does, not what area it touches
- Be specific enough to distinguish from other PRs in the same project
- Keep under ~70 characters when possible
- Match the project's title convention (check recent merged PRs)
- Include ticket/issue references if the project convention expects them in titles

**Calibration examples:**

<examples>

- Bad: "Fix bug"
- Good: "Fix login button unresponsive on Safari"

<!-- -->

- Bad: "Update CSS"
- Good: "Refine grid layout for mobile responsiveness"

<!-- -->

- Bad: "Changes for tax calculation"
- Good: "Add Swiss tax calculation for new regulation"

<!-- -->

- Bad: "Phase 1" / "Add patch" / "Various improvements"
- Good: "Add rate limiting to authentication endpoint"

</examples>

If the project uses conventional commits for PR titles:

```
fix(auth): resolve session expiry race condition
feat(api): add rate limiting to public endpoints
docs(readme): update installation instructions for v3
```

## PR Descriptions

The description is a permanent record. It must communicate **what** changed and **why** — not just repeat the diff.

### Required Elements

- **Summary** — one sentence stating what the PR does (imperative mood)
- **Problem** — what was wrong, missing, or needed; link to the issue
- **Approach** — why this solution; mention alternatives if the choice is non-obvious
- **Testing** — how changes were verified

### Conditional Elements

- **Trade-offs** — known limitations or deferred work (include when applicable)
- **Visual evidence** — before/after screenshots for UI changes (always include for visual changes)
- **Migration notes** — if the change requires action from others
- **Scope boundaries** — what was explicitly not addressed

### Anti-Patterns

- Do not narrate the diff — "Changed X to Y on line 42" adds nothing
- Do not leave descriptions empty — ever
- Do not use filler language: "This comprehensive PR improves...", "I've made the following enhancements..."
- Do not over-explain trivial changes — a typo fix needs one line
- If a PR template exists, fill every section. Do not delete sections; write "N/A" if genuinely not applicable.

For detailed description structure, templates, and scaling guidance, read
`${CLAUDE_SKILL_DIR}/references/pr-descriptions.md`.

## Fork Workflow

When contributing to a repository you do not have write access to:

- Fork the repository, clone your fork, add `upstream` remote pointing to the original
- Never commit to your fork's default branch — create a feature branch for each contribution
- Sync with upstream before starting work and before submitting
- Rebase onto latest upstream before opening the PR to minimize merge conflicts
- Enable "Allow maintainer edits" so maintainers can push small fixes to your branch

For complete fork mechanics and gh CLI commands, read `${CLAUDE_SKILL_DIR}/references/fork-workflow.md`.

## User Approval Gate

**Do not create the pull request until the user explicitly approves it.** After completing the pre-submission checklist,
present the full draft to the user — title, description, target repository, base branch, and any labels. Wait for
explicit approval before executing `gh pr create` or any equivalent action. The user may request changes; iterate until
approved.

## GitHub / gh CLI

When the target project is on GitHub, use `gh` for PR creation:

```bash
# Check for existing PRs and issues first
gh search prs --repo OWNER/REPO "keywords" --state all
gh search issues --repo OWNER/REPO "keywords" --state all

# Create PR from fork
gh pr create \
  --title "Fix login timeout on slow connections" \
  --body "$(cat pr-description.md)" \
  --base main

# Create draft PR for early feedback
gh pr create --draft --title "[WIP] Add rate limiting" --body "..."

# Check CI status after submission
gh pr checks
```

For non-trivial changes, open a draft PR early — before the work is complete. This gets feedback on approach before
heavy investment, and signals to maintainers that you're working on the problem.

## Agent-Specific Discipline

AI agents producing PRs must apply extra rigor to avoid the failure patterns that cause maintainer distrust.

- **Prove the change was requested** — link to an issue, discussion, or maintainer request. PRs that appear from nowhere
  with no connected issue trigger suspicion.
- **Demonstrate