laitszkin/open-source-pr-workflow

Open Source PR Workflow

Dependencies

• Required: commit before publishing the contribution branch (any remaining changes MUST be committed/readiness-checked through that skill; push only when the user requested remote update—then continue to PR steps).
• Conditional: code-simplifier for code-affecting PRs before opening the PR.
• Optional: none.
• Fallback: If commit or a required code-affecting dependency is unavailable, stop and report the missing dependency instead of bypassing the quality gate.

Standards

• Evidence: Assume implementation is already prepared, then verify PR scope, repository constraints, and validation commands from the actual change set.
• Execution: Create a compliant branch, run commit when the working tree still needs a gated commit, run dependent skills for code changes, then draft and open the PR.
• Quality: Target the upstream parent repository by default for forks, keep PR content in English unless requested otherwise, and exclude internal workflow details.
• Output: Produce a review-ready PR body with motivation, engineering rationale, test commands, and any required issue linkage.

Scope Guardrails

• This skill is for PR preparation and PR creation only.
• Do not use this skill as the primary workflow for implementing features or fixing code.
• If code changes are still needed, finish implementation in another workflow first, then return to this skill for PR handling.

Workflow

1) Clarify PR scope

• Identify related issue links/IDs and summarize the motivation for the change.
• Confirm target base branch and contribution constraints from the repository.
• Detect whether the current repository is a fork (for example with gh repo view --json isFork,parent,nameWithOwner).
• If it is a fork, default the PR destination repository to the upstream parent repository.
• Only target the fork repository when the user explicitly asks for it.

2) Create a compliant branch name

• Always use this pattern for PR branches: codex/{change_type}/{changes}.
• Convert both {change_type} and {changes} to lowercase kebab-case ([a-z0-9-] only).
• If the current branch name does not match, create a new compliant branch from current HEAD before opening PR.

Example:

git checkout -b codex/fix/add-rate-limit-retry

3) Record changes with commit

• If git status shows uncommitted work on the PR branch, run commit through commit (and push when the user explicitly asked to publish the branch remotely) before PR creation—MUST NOT bypass readiness/review gates that skill applies.
• If the tree is already clean with commits present, skip only after confirming there is nothing left to stage.

4) Run dependent skills for code-affecting changes

• If the PR includes code changes, run code-simplifier before opening the PR.
• Use these skills as internal quality gates only; do not include skill/tool names in PR content.
• If the PR has no code changes, explicitly note that these two skills were not required in internal notes only.

5) Verify existing changes (no feature implementation in this skill)

• Assume code/documentation changes are already prepared before entering this workflow.
• Do not add new feature implementation in this skill.
• After the dependent skills step (when required), run relevant checks (lint/test/build) based on repository conventions.
• Record exact test commands and outcomes for PR content.

6) Prepare PR content (show draft only on request)

• Draft the PR title and full PR body before creating the PR.
• Keep PR content strictly about the PR itself (motivation, changes, rationale, tests).
• Do not include internal workflow details such as skill names, tool names, or agent process notes.
• By default, proceed directly to PR creation after the title/body are ready.
• Show the draft only when the user explicitly asks to review it before creating the PR.
• If the user asks for draft edits, revise accordingly and get final confirmation before creating the PR.

7) Open the PR

• Prefer gh pr create to open the PR.
• If the repository is a fork, target the upstream parent repository by default (for example gh pr create --repo <upstream-owner>/<upstream-repo> --head <fork-owner>:<branch>).
• Use the fork as the PR destination only when the user explicitly requests it.
• Ensure PR title/body are in English by default.
• Switch language only when the user explicitly requests another language.

Required PR Body Structure

Use this structure (or equivalent headings) every time:

## Related Issues / Motivation
- Related: #<issue-id> (or link)
- Why this change is needed

## Engineering Decisions and Rationale
- Key implementation choices
- Why each choice was made
- Trade-offs considered (if applicable)

## Test Results and Commands
- ✅ `command 1`
- ✅ `command 2`
- Summary of outcomes

### Test Cases (for complex changes)
- Case 1: input/scenario -> expected result
- Case 2: input/scenario -> expected result

If tests cannot run locally, state why and provide the closest available validation evidence.

Pre-PR Checklist

• Branch name matches codex/{change_type}/{changes}.
• If the user asked to review the draft, they confirmed the final draft before PR creation.
• If the repository is a fork, PR destination is the upstream parent unless the user explicitly requested the fork.
• PR body includes all required sections and focuses only on PR-related context.
• If code changes exist, run code-simplifier before opening the PR.
• PR body does not mention internal skills/tools or agent workflow notes.
• Test commands and results are explicitly listed.
• Language defaults to English unless user requests otherwise.