PR Writer

PR Writer

Prepare pull requests end-to-end by generating the PR description and handling the publish flow (commit -> branch -> push -> PR creation when needed).

When to Activate

• User asks to write, open, or update a PR
• User asks to commit, push, and open a PR for current branch changes
• User says "ship this", "publish this", "make a PR", or similar

End-to-End Publish Workflow

[!IMPORTANT] If the current branch already has an open PR, always ask the user before doing anything else whether the new work should (a) be pushed as additional commits to the existing PR, or (b) go on a new branch (off the appropriate base, usually main) as a separate PR.

Never assume the user wants to extend the open PR, even if the new work feels related. Scope, review timing, and merge-queue considerations are the user's call. Do not commit, branch, or push until the user has answered.

1. Check repository and PR state

   • Confirm current branch and dirty working tree using git status.
   • Check if branch already has an open PR:
     • gh pr view --json number,url,headRefName,baseRefName,state
   • If an open PR exists on the current branch, stop and ask the user whether to push to that PR or start a new branch. Wait for the answer before proceeding to any other step. Quote the existing PR's number/title/URL in the question so the user can decide with full context.
   • If the user picks "new branch", create it off the appropriate base (usually main) in step 4 below before any commit.

2. Generate PR description body

   • Produce the PR body using the template in this skill (mirrors .github/pull_request_template.md).
   • Ensure title is a clear, sentence-case description of the change (see conventions below).

3. Commit current changes

   • Treat the current branch working tree as source of truth even if prior session history is unavailable.
   • Include both staged and unstaged tracked code/doc/config changes that are relevant to the PR scope.
   • Exclude obvious temporary artifacts (for example root-level screenshots, ad-hoc logs, dumps, tmp/debug files) unless explicitly requested.
   • Stage relevant files and create a commit with a clear message.
   • Include the standard co-author trailer unless the user opts out:
     • Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
   • If there are no changes to commit, skip commit creation and continue.

4. Create or switch to a publish branch

   • If current branch is a protected/shared branch (for example main), create a feature branch with a hyphenated descriptive name.
   • Otherwise keep using current feature branch.

5. Push branch

   • Push with upstream tracking:
     • git push -u origin <branch>
   • Never force-push to update a PR. Do not use git push --force or git push --force-with-lease under any circumstance. To update a PR, always add a new commit on top — never rewrite, amend, or squash already-pushed history. If the push is rejected as non-fast-forward, stop and ask the user; do not "fix" it with force.

6. Create PR only if one does not already exist

   • If no open PR exists for the branch, create one:
     • gh pr create --title "<title>" --body "<body>" --base main --head <branch>
   • If PR already exists, update body/title as needed instead of creating duplicates.
   • Update existing PR metadata when work is already partially published:
     • gh pr edit <PR_NUMBER> --title "<title>" --body "<body>"
   • If branch and PR already exist and no new commit is needed, run metadata update only.

7. Return publication result

   • Report commit SHA, branch name, push status, and PR URL.

Partial-State Handling (Some Steps Already Done)

• Existing branch + existing PR + new code changes:
  • Ask the user first whether the new changes belong on this PR or on a new branch (see the IMPORTANT callout above). If "this PR": commit/push changes, then update PR body/title with gh pr edit. If "new branch": create a fresh branch off main and run the normal flow there.
• Existing branch + existing PR + no code changes:
  • Skip commit/push and update PR description/title only.
• Existing branch + no PR:
  • Push branch if needed, then create PR with generated body.
• No branch/PR yet:
  • Create branch, commit, push, then create PR.
• Session reset/compaction or new-agent context with unknown edit history:
  • Do not rely on prior agent edit memory.
  • Use the current git status/diff as the canonical change set, apply temp-file filtering, then proceed with normal commit/push/PR flow.

Branch Naming Convention

This repo uses hyphenated descriptive branch names (no username prefix):

citation-config
citation-config-followup
configurability-followup
style-configurability
text-fonts-refactor
latex-configurability

PR Title Conventions

Use a clear, sentence-case description of the change. No [TAG] prefixes, no ticket IDs, no conventional-commit prefixes are required.

Examples (from recent merged PRs):

• Convert CitationCoder to public Hashable struct on CitationConfig
• Clean up InlineCitationConstants and merge citation predicates
• Add CitationConfig to MarkdownRenderConfig; remove dead Typography props
• Style folder; UIFont inline link/code; optional letterSpacing/lineHeight
• Introduce TextFonts struct and decouple style config from Typography enum

PR Template

The repo template (.github/pull_request_template.md) has three sections plus an OSS-readiness checklist:

## Summary

<!-- What changed and why? -->

## Validation

<!-- List the checks you ran, for example: make test && make build -->

## OSS readiness

- [ ] No secrets, internal URLs, private identifiers, or product-only service names were added.
- [ ] Public docs, fixtures, or notices were updated if behavior or dependencies changed.
- [ ] Third-party dependency changes (adds, removes, version bumps) are intentional and reviewed.
- [ ] Streaming/incomplete markdown behavior remains covered by fixtures or tests.

Template Filling Guidelines