create-pr

name	create-pr
description	Create a pull request from the current branch to develop with the repository template, a clear title, and issue linkage or a no-issue rationale.

Codex invocation: use $create-pr or select this skill through /skills. References below to /create-pr describe the source repository command.

Use this command when the user wants to create a GitHub pull request from the current branch to develop, either linked to a specific GitHub issue or explicitly marked as not closing an issue.

This command is part of the workflow in docs/how-to/ai-assisted-development-workflow.md.

The expected result is one open pull request from the current branch to develop, using the repository pull request template, containing either a closing reference to the provided issue or a clear no-issue rationale, and using a clear title that follows the release classification rules in docs/how-to/ai-assisted-development-workflow.md.

Input

This command expects /create-pr <issue-reference> or /create-pr no issue.

<issue-reference> can be a GitHub issue number or issue URL for the current repository.

If no issue reference is provided, ask the user which GitHub issue the pull request should close, or whether the pull request intentionally has no issue, and stop.

If the user says the pull request closes no issue, continue only after recording that no-issue decision for the pull request body.

Preconditions

Before creating the pull request, verify that:

• the current GitHub repository can be identified;
• the current branch can be detected;
• the current branch is not the repository default branch;
• develop exists locally or on the remote and can be used as the pull request base;
• when an issue reference is provided, it resolves to an existing issue in the current repository;
• when an issue reference is provided, the issue can be read through GitHub MCP, GitHub CLI gh, or another configured GitHub integration;
• the repository pull request template under .github can be read, including the selected template path when multiple templates exist;
• the working tree state is understood, including staged, unstaged, and untracked changes.

Use the most direct reliable GitHub integration available in this order:

• GitHub MCP when repository identity, branch, and issue reference are clear;
• GitHub CLI gh when MCP is unavailable or unsuitable;
• another configured GitHub integration only when it is the most reliable available option.

If the repository, branch, develop base branch, pull request template, required issue details, or GitHub integration cannot be determined safely, report what is missing and stop before creating the pull request.

If the working tree has staged, unstaged, or untracked changes, summarize the changes and ask the user whether to commit them before creating the pull request. Do not stage, commit, discard, or overwrite local changes unless the user explicitly confirms that action.

Workflow

1. Resolve the issue reference or explicit no-issue decision from $ARGUMENTS.
2. Detect the current repository, current branch, develop base branch, and remote tracking state.
3. If an issue reference was provided, read the issue title, body, state, labels, and URL.
4. Read the repository pull request template from .github and use the full template as the required pull request body format.
5. Check for an existing open pull request from the current branch to develop. If one exists, report it and ask whether to update the existing pull request, create a separate pull request, or stop.
6. Inspect the current branch commits and diff against develop to summarize the pull request accurately.
7. Check git status for staged, unstaged, and untracked changes.
8. If the working tree is not clean, summarize the changed files and ask whether to create a commit before continuing.
9. If the user wants a commit, inspect staged and unstaged changes, stage only the relevant files confirmed by the user, create a concise commit, and verify the working tree state again.
10. If the user does not want a commit, continue only if the existing branch commits are sufficient for the pull request. If the branch has no committed changes compared with develop, explain that there is nothing to include and stop.
11. Before creating the PR, compare code/test changes with docs/** changes. If code or tests changed but docs did not, verify the issue and existing docs contain a concrete documentation decision that satisfies AGENTS.md.
12. For bug fixes, reject a generic "restores intended behavior" justification when the expected current behavior is not already documented. Ask the user to update docs first, or update them if that is in scope.
13. Fill the PR documentation section with the docs changed, or the exact existing document section that already covers the behavior. Do not leave a generic no-docs-required statement.
14. Push the current branch to the remote when it has no upstream or when local commits have not been pushed. Do not force push.
15. Draft a clear pull request title before creating or updating the PR.
16. Use feat, fix, or perf with scope desktop, core, or sdk-python only for user-facing or compatibility-relevant changes. Use unscoped docs, ci, test, chore, or refactor for internal work.
17. When a PR mixes user-facing API work with internal refactors, choose the title from the primary user-facing change and explain the refactor in the PR body. For example, use feat(sdk-python): add live and headless automation for a Python SDK API PR that also reorganizes repository structure.
18. Fill every applicable section in the pull request template with a concise summary, validation status, manual validation, risk, reviewer focus, documentation decision, and either Closes <issue-reference> using the resolved issue number or URL, or No issue: <reason> when the user explicitly said the pull request closes no issue. Keep template sections that do not apply and write Not applicable where the template requests it.
19. Create the pull request with GitHub MCP or gh pr create, targeting develop as the base branch unless the user explicitly requested a different base branch.
20. Verify the created pull request URL, the base branch is develop, and the body contains either the closing issue reference or the no-issue rationale plus full template sections.
21. Do not merge the pull request, close the issue manually, request reviewers, or change labels unless the user explicitly asks.

Required output

Report:

• command result status;
• GitHub integration used;
• current branch and develop base branch;
• issue reference, title, and URL, or the no-issue rationale;
• pull request title, number, and URL;
• whether the working tree was clean;
• whether a commit was created before the pull request;
• whether the branch was pushed;
• pull request template path used;
• closing issue reference or no-issue rationale included in the pull request body;
• documentation impact decision and docs changed or exact existing coverage used;
• any validation run or skipped, with the reason;
• final status and any remaining manual follow-up.