Create PR

Create PR

Create a GitHub PR from the current branch: handle uncommitted changes, generate a summary, submit, then watch the PR until it is in a ready state.

Step 1: Resolve Base Branch

Before doing anything else, identify the PR base branch. Prefer the branch's upstream base or the repository's default branch from git remote show origin. Fall back to origin/main only if the repo does not expose a default branch.

Remind the user to rebase onto the base branch if they have not already. Ask if they would like to proceed or rebase first.

Step 2: Check for Uncommitted Changes

Run git status to check for staged, unstaged, or untracked changes.

• If there are uncommitted changes, show the user what's outstanding and ask if they'd like to commit them before creating the PR.
• If the user says yes, stage the relevant files, draft a concise commit message based on the changes, and commit.
• If there are no uncommitted changes, move on.

Step 3: Gather Branch Context

Run these commands in parallel to understand the branch:

1. git log <base>..HEAD --oneline to see all commits on this branch.
2. git diff <base>..HEAD --stat to get the list of changed files.
3. git diff <base>..HEAD to understand what changed in each file.
4. git rev-parse --abbrev-ref HEAD to get the current branch name.
5. git status to check if the branch has been pushed to remote.

Step 4: Generate PR Title and Summary

Title: Generate a concise PR title (under 72 characters) that captures the intent of the change. Use conventional style: lowercase, imperative mood (e.g., "prevent chat list from reordering when renaming sessions").

Body: Generate a PR summary with these sections:

Section 1: Overview

Start with metadata tags, then a Problem/Solution block:

• **Category:** — one of: new-feature, improvement, fix, infrastructure
• **User Impact:** — one sentence describing what changed from the user's perspective. Write this as a standalone sentence a non-technical stakeholder would understand (e.g., "Users can now create and schedule repeatable tasks directly from the desktop app."). This line is used for project changelogs.
• **Problem:** — describe the user-facing confusion, mismatch, or friction this PR addresses.
• **Solution:** — explain how the change resolves that UX problem and, if applicable, why the approach was chosen.

Keep Problem + Solution to 2-4 sentences total. Prioritize intent and expected user experience, but include brief high-level implementation rationale when it explains reliability, maintainability, or code quality.

Section 2: Changes

Wrap this section in a collapsible <details> block with the summary "File changes".

Inside, list every changed file. For each file, use the filename as a bold header, then underneath write one or two sentences about what was changed and why. Focus on intent, not implementation details.

Format:

<details>
<summary>File changes</summary>

**path/to/file.ts**
What changed and why.

**path/to/other.rs**
What changed and why.

</details>

Step 5: Resolve And Link A GitHub Issue

Keep issue tracking lightweight and automatic. Complete the issue decision before pushing or creating the PR; a user request to create a PR is not permission to skip issue resolution.

Before creating the PR:

1. Look for an explicit GitHub issue reference in the current conversation, branch name, commit messages, PR title, or PR body.
2. If no issue is explicit, search the repository's open GitHub issues using the branch name, commit subjects, changed-file intent, and PR title.
3. If one issue clearly matches the same user need or implementation intent, use it. If a few issues could match, pause and ask the user which one to link. If none match, continue without creating an issue unless the user asks for one.

When an issue is resolved, include Closes #<number> in the PR body so GitHub links the work and closes the issue when the PR merges. Use Refs #<number> instead when the PR contributes to the issue without completing it. Verify the rendered PR shows the intended issue relationship.

Step 6: Push and Create PR

1. Push the branch to remote if it hasn't been pushed yet: git push -u origin HEAD
2. Create the PR using gh pr create with the generated title and body. Use a HEREDOC for the body to preserve formatting.
3. Output the PR URL as a clickable hyperlink so the user can open it directly.

Step 7: Watch the PR to a Ready State

Once the PR is created, do not stop. Own the loop from "PR is open" to "PR is in a ready state": watch GitHub, fix failing checks, and address review comments until checks pass and no actionable feedback remains. This step ends at a ready state — it does not merge the PR.

Keep track of the latest head SHA. Any new push changes the CI/review baseline and restarts this loop.

Poll feedback first, then CI

Use a non-blocking polling loop until both review feedback and CI have settled. Never use gh pr checks --watch or any other command that blocks until checks finish because review feedback commonly arrives while CI is still running.

Each polling cycle must run in this order:

1. Fetch all new top-level comments, review summaries, inline comments, and unresolved review threads.
2. If actionable feedback exists, evaluate and address it immediately. Do not wait for pending checks; any fix will restart CI anyway.
3. Only when no actionable feedback remains, fetch the current check states and handle failures or pending checks.
4. If checks are still pending and no feedback needs action, sleep for a fixed interval, then begin a new cycle from step 1.

Use whatever non-blocking commands are available, such as:

• gh pr view for PR state, reviews, comments, and mergeability.
• Repeated gh pr checks without --watch for current check status.
• gh run list, gh run view, and gh run rerun for workflow failures and reruns.
• GitHub API/GraphQL to inspect review threads and unresolved conversations.

After every code push, comment reply, or thread resolution, restart from the latest head SHA and begin with a fresh feedback sweep.