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. Lock the intended diff. Preserve unrelated worktree changes and meaningful existing PR content.
3. 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.
4. Commit the intended scope, run relevant checks, and push safely. Rewrite only a clearly user-owned topic branch and use --force-with-lease.
5. Write real Markdown to 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.
6. Verify the remote PR fields and report its URL, state, base/head, assignees, results, and any remaining caveat.
7. 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.
• Write every new or rewritten PR title and body in concise, plain English, regardless of the language used in the request or surrounding discussion. Preserve non-English text only when it is meaningful existing content, a required quotation, or a repository-specific identifier.
• A request to write PR copy does not authorize branch, push, or forge mutations. Enter this workflow only when publication intent is explicit.
• Prefer repository conventions over invented ones. If the repo has a PR template, read it, preserve its required headings and checklists, and remove unfilled placeholders. Do not append the fallback body shape to a repository template.
• Write for a reviewer encountering the work for the first time. Introduce the problem, affected behavior, and relevant constraints without referring to the current chat, earlier discussion, or private shorthand. Keep only context that changes how the reviewer understands, verifies, or acts on the PR.
• 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.
• Make the body scan-first. Omit process narration, obvious diff restatements, generic background, and empty sections. Do not turn the body into a long narrative or insert manual line breaks for line length.
• 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.

Shape And Recheck The Body

Read references/pr-body-guidance.md before writing a new body or substantially rewriting one. A repository template wins. Without one, default to ## Context and ## Changes; add ## Validation only for manual results CI cannot prove or a material CI caveat. Add other sections only when their trigger in the reference applies.

Link issues and design records without making them prerequisites for understanding the PR. Keep enough context in the body for future readers whose access or memory differs from the author's. 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 English title:

• fix: preserve PR body formatting
• docs: add draft PR skill
• refactor: simplify auth callback handling

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. 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.