Submit: from working tree to reviewable PR

This skill packages finished work so a reviewer can trust it. The commits read as history. The checks already pass. The description explains what the diff cannot. The PR opens as a draft and is gated on CI.

The commands below name gh. When origin is not GitHub, use the forge's equivalent, such as glab for GitLab. The phases stay the same.

Required references

Paths are relative to this file. <plugin root> is the directory two levels above it.

Consent

Invoking /submit is consent for the full workflow: commit, push, create or edit a draft PR, and push CI-fix commits. A narrower request such as "just commit" or "just push" is consent for exactly that. Confirm before stepping past it. Three actions always need fresh, explicit consent: pushing to the default branch, force-pushing, and marking a draft PR ready for review.

Workflow

Each phase meets its exit condition before the next one starts. A re-invocation re-enters at phase 0 and skips the phases already satisfied, never 5b or 6 while a PR exists.

0. Orient. Run touch "$(git rev-parse --git-dir)/swd-submit". The plugin's guard refuses gh pr create without this fresh marker. Then gather the facts: git status, the current branch, git log @{u}..HEAD, and gh pr view --json number,title,body,state,isDraft,baseRefName. State what you found in a sentence or two. A merged or closed PR means new work starts from a fresh branch off the updated default branch.
1. Branch. Never commit to the default branch. Follow the repo's branch naming when one is documented or visible. Otherwise use <author>-<slug>: the git user's first name in lowercase, and a slug from the change.
2. Commit, if phase 0 found uncommitted changes. Read references/commits.md and ../../assets/writing.md now. Stage by filename, and give each unrelated change its own commit. Lint each message with <plugin root>/scripts/prose-lint.py --commit before you commit.
3. Pre-push checks. Format, lint, and test every area the branch touches, with the repo's own commands from its agent docs, task runner, or package scripts. Fix failures at the root before pushing.
4. Push. The first push is git push -u origin <branch>, then plain git push. Exit: local HEAD matches origin/<branch>.
5. PR. Read references/pr-description.md and ../../assets/writing.md now.
   • 5a, no PR exists. Draft the title and the body. When the branch changes anything rendered, read references/screenshots.md: screenshots are mandatory, or the body declares the gap. Lint the body with prose-lint.py and fix every finding. Create the PR with gh pr create --draft.
   • 5b, a PR exists. Mandatory even when the user only said "push", and even with nothing new pushed. Fetch the live title and body and git log <base>..HEAD. Check that the title still covers all the work. Check that every claim in the body is still true. That covers the scope, statements such as "no new dependencies", the glance-block numbers and side effects, and the screenshots. Stale: edit with gh pr edit and say what changed. Not stale: state "title and body still match the branch".
6. CI. Run gh pr checks and wait out pending checks. Never declare success with checks in flight. On failure, read the failing logs, find the root cause, fix it, and re-enter at phase 3. Never disable a check or skip a test. Flag a failure that is clearly flaky or on the infra side to the user instead of retrying it. Close with the status: "all N required checks green", or what failed and which commit fixed it. Then run rm -f "$(git rev-parse --git-dir)/swd-submit".

Definition of done

• Phase 0 findings stated. No phase skipped silently.
• Work sits on a feature branch. Nothing pushed to the default branch.
• Every new commit has a Conventional subject and the trailer. No unrelated or sensitive files staged.
• Every commit body and the PR body pass prose-lint.py with no findings.
• Format, lint, and tests passed locally before every push.
• A draft PR exists. Each section of its description opens with its glance block. Rendered changes carry screenshots or a declared capture gap.
• On re-invocation, the title and body were revalidated and the outcome stated.
• All required CI checks green, or the flaky or infra failure flagged.
• Nothing marked ready, force-pushed, or merged without fresh consent.
• The swd-submit marker is removed.

Related skills

/blueprint plans the change. /examine reviews the PR once it exists. /rebase moves it when the base branch moved underneath it.