tomevault-io Context
- Project: !
git rev-parse --show-toplevel 2>/dev/null || echo "NOT_IN_GIT_REPO" - Current branch: !
git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "NO_BRANCH" - Base branch: !
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main" - Uncommitted changes: !
git status --porcelain 2>/dev/null | wc -l | xargs - Remote status: !
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "NOT_PUSHED" - Commits ahead: !
git rev-list --count @{u}..HEAD 2>/dev/null || echo "0"
Create GitHub Pull Request
Usage: /pr-creator - Create regular PR | /pr-creator draft - Create draft PR
Expert software engineer creating high-quality PR descriptions that facilitate efficient code review.
Pre-flight Checks
Validate environment:
- Check "Project" - if "NOT_IN_GIT_REPO", stop and inform user
- Check "Current branch" - if "NO_BRANCH", stop and inform user
- Check "Uncommitted changes" - if > 0, warn user and ask to continue
Stage 1: Analyze & Generate Draft
Step 1: Detect Mode & PR Type
Mode: Check $1 equals "draft" → draft PR, else regular PR
Classify PR type via git log origin/{base}..HEAD --format="%s":
- Feature: feat:, add, implement, create, new functionality
- Fix: fix:, bug, resolve, patch
- Refactor: refactor:, restructure, clean up
- Docs: docs:, changes to *.md
- Test: test:, test file changes
- Chore: chore:, maintenance, deps, config
Step 2: Gather Information
Inspect changes:
git log origin/{base}..HEAD
git diff origin/{base}...HEAD --stat
git diff origin/{base}...HEAD
gh issue list --limit 20 # Search for related open issues
Look for: External reference IDs in commits/branch name (GitHub issues, Jira tickets, Sentry issues, PagerDuty incidents) | Related open issues via gh issue list | Breaking changes | New dependencies | Security changes (auth, validation) | Performance implications
Step 3: Generate Draft Description
Use structure from references/templates.md. Key principles:
- 6-12 lines maximum
- Three sections: Opening (1-2 sentences), Context (1-3 sentences), Implementation (2-4 bullets)
- Professional but conversational tone
- Specific technical terms, no marketing language; backtick-wrap code identifiers (env vars, functions, paths, endpoints)
- Plain bullets (
-), no bold/headers in body; no hard line wraps in prose paragraphs - Issue refs at end with proper keywords; all external references as clickable markdown links (see
references/templates.md) - Never include a "Test Plan" or "Testing" section -- leave test planning to humans
See references/templates.md for detailed structure and examples.
Step 4: Present Draft & STOP
Present draft to user and STOP. Wait for explicit approval.
When presenting:
- Indicate draft/regular PR mode
- Ask to proceed or revise
Stage 2: Create Pull Request
Only after explicit user approval.
Verification
Check for PLAN files:
git log origin/{base}..HEAD --name-only --pretty=format: | grep -q "^PLAN" || git ls-files | grep -q "^PLAN"
If found: STOP - PLAN files are dev docs that shouldn't be in PRs. Provide remediation: Remove PLAN files and amend/rebase OR Create clean branch without PLAN files
Ensure branch pushed:
# If Remote status = "NOT_PUSHED":
git push -u origin HEAD
Create PR
Extract title from opening paragraph (50-70 chars)
Create (use HEREDOC for formatting):
Regular:
gh pr create --title "Title" --base {base} --body "$(cat <<'EOF'
[Full approved description]
EOF
)"
Draft:
gh pr create --title "Title" --base {base} --draft --body "$(cat <<'EOF'
[Full approved description]
EOF
)"
Display PR URL upon success.
Critical Requirements
Approval Gate: NEVER skip user approval | ALWAYS present draft and wait | Accept revisions | Only proceed after clear approval
Accuracy: Inspect actual commits via git | Review code changes via diff | Don't rely solely on commit messages | Verify issue refs exist | Derive URLs for external references from context (never hardcode base URLs)
Structure: Follow 3-section format (opening, context, implementation) | 6-12 lines maximum | Proper issue ref formatting
Branch Management: Verify branch pushed before PR | Use git push -u origin HEAD if needed | Confirm base branch correct | Block PRs with PLAN files
Formatting: Always use HEREDOC in gh pr create --body | Ensure proper line breaks/bullets | Blank line before issue refs
Goal: Create PR descriptions making code review efficient and thorough, providing reviewers all context to understand and evaluate changes quickly.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.