oss-submit-pr

# Submit PR

Get your PR right the first time. This skill checks your work against the repo's rules, catches common rejection reasons, and helps you write a PR description that maintainers actually want to read. You write the description. the LLM reviews it.

## Purpose

A clean PR gets reviewed and merged. A sloppy PR gets ignored or closed. Most new contributors get rejected not because their code is bad, but because they didn't follow the process. wrong branch, missing tests, unclear description, scope creep. This skill catches all of that before you hit submit.

## Prerequisites

- Implementation complete (from `oss-contribute`)
- Tests pass locally
- Lint/formatting passes locally
- User can explain what they changed and why (verified in `oss-contribute` step 6)

## Process

### 1. Re-read contribution requirements

Even if `oss-prep-to-contribute` already read these, read them again. specifically for PR submission rules:

```bash
# Fetch latest CONTRIBUTING.md
gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md --jq '.content' | base64 -d 2>/dev/null

# Check for PR template - all standard locations
for path in \
  ".github/PULL_REQUEST_TEMPLATE.md" \
  ".github/pull_request_template.md" \
  "PULL_REQUEST_TEMPLATE.md" \
  "pull_request_template.md" \
  "docs/PULL_REQUEST_TEMPLATE.md" \
  "docs/pull_request_template.md"; do
  if content=$(gh api "repos/{owner}/{repo}/contents/$path" --jq '.content' 2>/dev/null); then
    printf '%s' "$content" | base64 -d 2>/dev/null
    break
  fi
done

# Check for multiple PR templates (directory-based)
gh api "repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE" \
  --jq '.[] | .name' 2>/dev/null
```

**If a single template is found**: use it. The PR description must follow its structure exactly.

**If a template directory exists with multiple templates**: present each template name to the user and ask which one matches their contribution type (bug fix, feature, docs, etc.). Fetch the selected template and use it.

**If no template is found**: no template required. follow the general PR description guidance below.

Extract PR-specific requirements:
- PR template (must follow if present. check ALL locations above)
- Branch naming convention
- Commit message format (conventional commits? sign-off required? DCO?)
- Squash policy (squash before merge? maintainer squashes?)
- Linked issue format ("Fixes #123" vs "Closes #123" vs "Resolves #123")
- Required reviewers or labels
- CI checks that must pass

### 2. Pre-flight checks

Run every check the CI will run. locally, before pushing:

```bash
# Rebase on latest upstream
git fetch upstream
git rebase upstream/main

# Run tests
# {repo-specific test command}

# Run linting/formatting
# {repo-specific lint command}

# Check the diff is focused
git diff upstream/main...HEAD --stat
```

### 3. Review the diff

Go through the entire diff and flag issues:

```bash
git diff upstream/main...HEAD
```

Check for:

| Check | What to look for |
|-------|-----------------|
| **Scope creep** | Changes to files unrelated to the issue |
| **Debug leftovers** | console.log, print(), debugger, TODO comments |
| **Style drift** | Naming that doesn't match repo conventions |
| **Missing tests** | Code changes without corresponding test changes |
| **Commented-out code** | Dead code that shouldn't be committed |
| **Unrelated formatting** | Whitespace-only changes to lines you didn't modify |
| **Hardcoded values** | Magic numbers, hardcoded strings that should be constants |
| **Error handling** | New code paths without error handling (if repo expects it) |

For each issue found, present it to the user with the exact location:

> "Found a potential issue at `src/foo.ts:42`: you left a `console.log` from debugging. Remove it before submitting."

Don't auto-fix. Tell the user what and where.

### 4. Verify commit conventions

```bash
# Check commit messages against repo conventions
git log upstream/main..HEAD --oneline
```

If the repo uses conventional commits and the user's messages don't conform, explain the format and ask them to amend. If sign-off is required:

```bash
# Check for sign-off
git log upstream/main..HEAD --format='%B' | grep -c 'Signed-off-by'
```

### 5. Thinking gate: user writes the PR description

**The user writes the PR description, not the LLM.**

Tell the user:

> "Write your PR description. Start with one sentence: what does this PR do?
>
> Then add:
> 1. Link to the issue ('Fixes #{number}')
> 2. Why this approach. remember the trade-offs from /oss-contribute? Mention the key one
> 3. How you tested it. what did you run, what passed?
>
> Keep it short. If the repo has a PR template, follow it. Write in your own words. I'll review it after."

Wait for the user to write it.

### 6. Review the PR description

Once the user has written their description, review it for **conciseness and clarity**:

- Does it link the issue? ("Fixes #{number}")
- Does it follow the repo's PR template structure? (If a template was found in step 1, every section from the template must be addressed)
- Is it **short and direct**? Maintainers review dozens of PRs. they skim
- Does it explain non-obvious decisions **without over-explaining obvious ones**?
- Does it mention how the change was tested?

**Writing rules for PR descriptions:**
- Lead with what changed, not why you're writing
- One sentence per point. No paragraphs where a bullet works
- No filler: "This PR addresses the issue where..." → "Fixes null check in auth handler"
- No AI jargon: "comprehensive", "robust", "leverages", "utilizing". Cut all of it
- No self-narration: "I noticed that..." / "After investigating...". Just state the facts
- Technical terms are fine. Buzzwords are not
- If the PR template asks for something, answer it. Don't add extra sections

Give specific feedback:

> "Your description is good, but trim the first paragraph. the reviewer doesn't need the backstory. Lead with what changed."

Don't rewrite it. give feedback and let