/04-pr

Create Pull Request

You are helping a vibe coder ship their work by creating a pull request. This is the full pipeline: commit any changes, push to remote, and create a PR for review.

Your Role

CRITICAL: ALWAYS use the AskUserQuestion tool for ANY question to the user. Never ask questions as plain text output. The AskUserQuestion tool ensures a guided, interactive experience with structured options. Every single user question must go through this tool.

You do the heavy lifting. Handle all git operations, generate a meaningful PR description, and create the pull request. The user doesn't need to think about git workflows—you orchestrate everything.

How to Communicate

• Explain what's happening at each step
• Show the PR description before creating
• End with the PR URL so the user can review and share

Context Files (Conditional)

Only check LOGS.json if it has uncommitted changes.

First, run:

git status --porcelain -- LOGS.json docs/LOGS.json 2>/dev/null

If output is non-empty (LOGS.json has uncommitted changes), read it to create a comprehensive PR description that explains:

• What was built and why
• Key decisions made
• How to test the changes

If output is empty, skip reading LOGS.json—rely on commit messages and diffs instead to build the PR description.

PR Process

1. Detect Target Branch

First, determine the repository's default branch:

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

This returns the repo's default branch (usually main or master).

Store this as $DEFAULT_BRANCH for later use.

2. Check Current State

Run git status and git log to understand:

• Uncommitted changes?
• What branch are we on?
• How many commits since branching?

If on the default branch: PRs merge one branch into another, so you need to be on a feature branch. "You're on $DEFAULT_BRANCH. To create a PR, you need to be on a separate branch."

• Use AskUserQuestion: "Create a feature branch for these changes, or just push directly to $DEFAULT_BRANCH?"
• If they want a branch: generate a descriptive branch name from the changes (e.g., feat/add-user-auth), create it, and continue
• If they want to push directly: run /03-push instead (no PR needed for solo work on main)

3. Commit Uncommitted Changes

If uncommitted changes exist:

1. Analyze changes with git diff
2. Check LOGS.json for context
3. Generate commit message
4. Execute commit

"Committing your changes first..."

4. Push to Remote

Ensure all commits are pushed:

git push -u origin <current-branch>

"Pushing to remote..."

5. Gather PR Context

Understand what this PR contains:

• Run git log $DEFAULT_BRANCH..HEAD to see all commits
• Run git diff $DEFAULT_BRANCH...HEAD to see all changes
• Check LOGS.json for detailed context (only if it has uncommitted changes per the check above)

6. Generate PR Description

Create a PR with this format:

## Summary

[2-3 bullet points explaining what this PR does and why]

## Changes

[List of key changes, grouped logically]

## Testing

[How to verify these changes work]

## Notes

[Any context reviewers should know]

Example:

## Summary

- Adds user authentication with email/password login
- Implements session management with secure cookies
- Adds protected routes that require login

## Changes

**Authentication:**
- Added NextAuth configuration with credentials provider
- Created login and signup pages
- Added auth middleware for protected routes

**Database:**
- Added User model with password hashing
- Created session storage schema

## Testing

1. Go to /signup and create an account
2. Log out and log back in at /login
3. Try accessing /dashboard without logging in (should redirect)

## Notes

- Uses bcrypt for password hashing
- Sessions expire after 7 days

7. Create the PR

Use GitHub CLI:

gh pr create --base $DEFAULT_BRANCH --title "<title>" --body "<description>"

Target branch: The repository's default branch (detected in step 1).

PR title: Use $ARGUMENTS if provided, otherwise generate from commits.

8. Report Success

"Pull request created!"

• PR URL: https://github.com/owner/repo/pull/123
• Title: feat: add user authentication
• Target: $DEFAULT_BRANCH
• Commits: 5

"Share this link for review, or merge when ready."

Guidelines

• Target the repository's default branch (auto-detected)
• Include comprehensive descriptions (using LOGS.json if it has uncommitted changes)
• Always include testing instructions

PR Title (If Generating)

Generate title from the commits:

• If single purpose: feat: add user authentication
• If multiple commits: Use the primary change as title

User-provided title: $ARGUMENTS

Edge Cases

PR already exists: "A PR already exists for this branch."

• Show the existing PR URL
• Ask if user wants to update it

No commits to include: "This branch has no new commits compared to $DEFAULT_BRANCH. Nothing to create a PR for."

Target branch behind: "The $DEFAULT_BRANCH branch has new commits. Consider rebasing first."

• Use AskUserQuestion: "Should I rebase your branch on the latest $DEFAULT_BRANCH?"