GitHub PR creation

Creates Pull Requests with task validation, test execution, and Conventional Commits formatting.

Current state

!

git rev-parse --abbrev-ref HEAD 2>/dev/null

git log @{u}..HEAD --oneline 2>/dev/null || echo "(no upstream tracking)"

Core workflow

1. Confirm target branch

ALWAYS ask user before proceeding:

Creating PR from [current-branch] to [target-branch]. Correct?

2. Search for task documentation

Look for task/spec files that describe what this PR should accomplish. Common locations by tool:

.s2s/plans/*.md

.kiro/specs/*/tasks.md

.cursor/rules/*.md

.cursorrules

.trae/rules/*.md

gh issue list --assignee @me --state open

docs/specs/

specs/

tasks.md

TODO.md

Extract task IDs, titles, descriptions, and requirements references when found.

3. Analyze commits

For each commit on this branch, identify type, scope, task references, and breaking changes. Map commits to documented tasks when task files exist.

4. Verify task completion

If task documentation exists:

1. Identify main task from branch name (e.g.,

   feature/task-2-*

   -> Task 2)
2. Find all sub-tasks (e.g., Task 2.1, 2.2, 2.3)
3. Check which sub-tasks are referenced in commits
4. Report missing sub-tasks

If tasks incomplete, STOP and show status:

Task 2 INCOMPLETE: 1/3 sub-tasks missing
- Task 2.1: done
- Task 2.2: done
- Task 2.3: MISSING

Ask user whether to complete missing tasks or proceed anyway.

5. Run tests

Run the project test suite. Tests MUST pass before creating PR.

6. Determine PR type and generate title

feat(scope):

fix(scope):

hotfix(scope):

release:

refactor(scope):

chore(scope):

ci(scope):

docs(scope):

Title format:

<type>(<scope>): <description>

• Type: dominant commit type from analysis (feat > fix > refactor > ci > chore)
• Scope: most common scope from commits (kebab-case)
• Description: imperative, lowercase, no period, max 50 chars

Breaking changes: if any commit contains

BREAKING CHANGE:

!

• Add

  breaking

  label if it exists in the project
• Include a

  ## Breaking changes

  section in the PR body

7. Generate PR body

Use the appropriate template from

references/pr_templates.md

8. Suggest labels

ALWAYS check available labels first:

gh label list

Match commit types to available project labels. The project may use different names than standard (e.g., "feature" instead of "enhancement").

If no matching label exists: suggest creating one. The user may have removed default labels, so offering to add relevant ones is appropriate.

9. Determine milestone

Check for open milestones:

gh api repos/$(gh repo view --json nameWithOwner -q '.nameWithOwner')/milestones \
  --jq '.[] | select(.state == "open") | "\(.number): \(.title)"'

• If one active milestone exists: assign the PR to it (all work in progress belongs to the next release)
• If multiple milestones exist: ask the user which one applies
• If no milestones exist: skip (do not create one automatically)

10. Create PR

ALWAYS show title, body, labels, and milestone for user approval first.

gh pr create \
  --title "[title]" \
  --body "$(cat <<'EOF'
[body content]
EOF
)" \
  --base [base_branch] \
  --label "[label1]" --label "[label2]" \
  --milestone "[milestone-title]" \
  --reviewer "[username]"          # if teammates are known

Use

--draft

Important rules

• ALWAYS confirm target branch with user
• ALWAYS run tests before creating PR
• ALWAYS show PR content for approval before creating
• ALWAYS check available labels with

  gh label list

  before suggesting
• ALWAYS use HEREDOC for body to preserve formatting
• ALWAYS add

  --label

  for each label separately (not comma-separated in one string)
• ALWAYS check for open milestones and assign if one is active
• NEVER create PR without user confirmation
• NEVER modify repository files (read-only analysis)
• NEVER create a milestone automatically - only assign existing ones
• Use

  --draft

  for PRs not ready for merge review
• Use

  --reviewer

  when teammates are known from team config or CODEOWNERS

References

• references/pr_templates.md

  - PR body templates for all types (feature, release, bugfix, hotfix, refactoring, docs, CI/CD)