draft-pr

Draft PR

Publish the requested work as a draft or work-in-progress PR on the forge that owns the selected remote. Update or squash-merge it only on a corresponding request. Lead the final response with the PR URL and verified state.

Quick Start

1. Preflight Git state, publication remote, forge, exact head and target repositories, provider authentication and authenticated user, base branch, and any existing PR for the current branch.
2. Resolve the PR language from the user's instruction, repository guidance, or clear team practice. Ask only when those sources leave a consequential ambiguity.
3. Lock the intended diff. Preserve unrelated worktree changes and meaningful existing PR content.
4. Create a topic branch when on the base branch. Fetch the target remote and rebase only when the topic branch is behind, conflicted, or explicitly needs synchronization.
5. Commit the intended scope, run relevant checks, and push safely. Rewrite only a clearly user-owned topic branch and use --force-with-lease.
6. Write the title and body in that language as real Markdown in a temporary file, create a draft or work-in-progress PR or update the existing PR through the selected provider adapter, then assign the authenticated user by default.
7. Verify the remote PR fields and report its URL, state, base/head, assignees, results, and any remaining caveat.
8. Merge only on explicit request. Recheck the exact PR and gates, squash-merge through the same adapter, and verify the merged state.

A PR request grants scoped commits and push; do not ask again. If publication is blocked, name the failed command or rule and finish authorized local work.

Do not broaden the task into unrelated refactors, repository cleanup, or rewriting manually maintained PR content.

PR Rules

• Select the provider from the publication remote and resolve the head and PR target repositories separately when working from a fork. Do not select a forge from the name origin, an installed CLI, or a nearby account.
• Use authenticated gh for GitHub and GitHub Enterprise and authenticated fj for Forgejo. Bind either CLI to the selected host and repository. Do not install or authenticate a CLI implicitly; use another adapter only when the user explicitly selects it.
• Confirm a working PR adapter before pushing. A successful Git push is not a PR. If the selected remote has no PR interface or provider authentication is unavailable, stop before mutation and route a push-only request to commit-and-push.
• Do not add model or agent identifiers such as codex/, claude/, [codex], [claude], “AI-generated”, “Generated by”, or co-author trailers to branch names, commits, PR titles, or PR bodies unless the user explicitly requests it.
• New PRs are draft by default. On Forgejo, use and verify the instance's recognized work-in-progress title prefix. Do not silently create a ready PR.
• Create and update requests do not authorize merging. An explicit merge request authorizes one squash merge only after the documented gates pass. Never switch methods, force a merge, remove a work-in-progress prefix, or delete the head branch merely to make the merge succeed.
• Use the login returned by the selected provider's authenticated-user lookup as the default assignee for new and existing PRs, while preserving current assignees. An explicit user choice of another assignee overrides this default. If the work context alone suggests assigning someone else, ask the user before adding them; never infer another person's assignment silently.
• Settle the PR language before writing the title or body, following the PR language rules below. Title and body share one language; conventional prefixes, identifiers, commands, paths, and quoted text keep their original form.
• A request to write PR copy does not authorize branch, push, or forge mutations. Enter this workflow only when publication intent is explicit.
• Keep the PR focused on one outcome. If no specific title can describe the whole diff in one sentence, report the scope mismatch instead of hiding it behind a generic title or long body.
• Preserve meaningful existing PR body content such as screenshots, links, issue references, release notes, or reviewer context. Do not overwrite an existing PR title unless the user asked to rewrite it or it is clearly a generated placeholder.

Publication Workflow

Before any Git or forge mutation, read and follow references/publish-workflow.md. It contains the provider selection, preflight, synchronization, body-file, assignment, and verification path. Keep the quick path above as the completion checklist.

PR Language

Reviewers read a PR in their team's working language, so the language is the user's call rather than a default that ignores where the PR lands. Resolve it in this order:

1. The user's explicit instruction for this PR or this repository.
2. A language the repository already states for PRs: a PR template, a contributor guide, or agent instructions that name one.
3. Clear team practice in the existing PR being updated or the repository's recent PRs. Use the README as supporting context, not proof that every team reviews in that language.
4. Ask once when the evidence is missing or conflicts. English is the default when the user has no preference; the author's company repositories use Korean unless a more specific instruction says otherwise.

Reuse a language already resolved for this repository in the session. When nobody can answer, as in an unattended run, apply the established repository or author default, else English, and say in the report which rule decided. A user who wants the answer to stick records it in the repository's contributor guide or agent instructions; publishing a PR does not edit those files.

Shape The Body

A body the reviewer does not read has failed. Say why the change exists and what changed, as a reviewer who did not see the work will meet it. Apply copydesk for shared meaning-preservation and writing guidance when available; this skill owns PR structure, language resolution, and publication authority. Read references/pr-body-guidance.md before writing a new body or rewriting one; it holds the default shape, the headings in each language, when a table beats bullets, the cut list, and worked examples.

• A repository template wins: fill its headings and checklists, remove unfilled placeholders, and do not append the fallback shape to it.
• Without a template, use ## Context for the problem, intent, and decision, then ## Changes for reviewer-visible outcomes, both in the PR language. A small change needs two or three sentences and no headings.
• Structure carries the reading: short paragraphs, one bullet per outcome, and one level of nesting when items group by component or theme.
• Use a table when several items share the same few attributes and the reviewer will compare them side by side, such as settings with their old and new defaults or endpoints with their new status. Design it before filling it: each column is one attribute named in its header, each row is one item, and a cell holds a value, an identifier, or a short phrase. A point that needs a full sentence goes in a bullet under the table, not in a cell.
• A PR that changes behavior, structure, defaults, or data flow always gets an as-is/to-be table, with the as-is side read from the real base branch at the merge base; follow Before And After in pr-body-guidance.md. Add no diagram or figure unless the user asks for one for this PR.
• No validation or testing section unless the template asks for one; the forge's checks and the commits are the record. Remove empty reassurance, generic disclaimers, courtesy closings, self-appraisal, process narration, restated diff, and references to the chat. Preserve actual uncertainty, operating conditions, compatibility limits, and known failures that change how the reviewer interprets or uses the change. State each beside the claim it qualifies.

Link issues and design records without making them prerequisites for understanding the PR. Immediately before publication, compare the title and body with the final diff and update descriptions that no longer match the branch.

Title Style

Use the repository's title convention when obvious. Otherwise use a concise present-tense title in the PR language, keeping the repository's conventional prefix when it uses one:

• fix: preserve PR body formatting
• docs: add draft PR skill
• refactor: simplify auth callback handling
• fix: PR 본문 서식 보존 when the team reads PRs in Korean

Avoid:

• [codex] fix PR flow
• Claude-generated pull request #123
• Update files
• Titles that merely repeat the branch name when the branch name is vague.

Output Contract

Report the provider, PR URL, remote state, base/head, assignees, action taken, commits and checks used, preserved reviewer context, and material caveats. When the user was not asked, name the PR language and the rule that settled it. For a merge, include the verified check state, resulting commit when available, and head-branch deletion state. On failure, name the exact command or remote condition and smallest next action. Never equate a push or an unverified merge command with a completed PR action.

Gotchas

• Multiline literal body arguments are fragile. Use --body-file wherever the selected CLI supports it. Follow the quoted file-expansion path documented for fj body edits because fj 0.6.0 supports --body-file only on create.
• fj is the Forgejo user CLI; the forgejo server binary is an administration CLI. Follow the version-specific draft and immediate-merge safeguards in the publication workflow.
• If the repository uses jj or another VCS layer, stop before running Git mutation commands and ask for the repo-specific publish path.