Github Pr Creation

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:

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

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: or ! after type:

• 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 based on PR type and populate with gathered data.

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 if the PR is not ready for merge review yet (work in progress, awaiting CI, or created only to trigger AI bot review on the branch).

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)

PR templates

Select the template matching the PR type.

---

Feature (feature/* -> develop)

Title: feat(<scope>): <description>

## What
- [List of implemented features/components]
- [Main functionality highlights]

## Why
- [Business/operational impact]
- [Pain points resolved]

## Details
### Task X.Y: [Task title]
- [Implementation detail 1]
- [Implementation detail 2]
- **Requirements**: X, Y, Z

## Checklist
- [ ] Main feature implemented
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Code review ready

---

Release (develop -> main)

Title: release: version X.Y with [main features]

## What
This release includes:
- [Feature set 1 - Task N]
- [Feature set 2 - Task M]

## Why
[Release motivation, milestone reached]

## Details
### Task N: [Feature name] (COMPLETE)
- **Task N.1**: [Description]
- **Task N.2**: [Description]
- **Requirements**: X, Y, Z

## Testing
- Coverage: XX%
- Integration tests: pass/fail

## Checklist
- [ ] All tasks completed
- [ ] No breaking changes (or documented)
- [ ] Migration guide prepared (if needed)

---

Bugfix (fix/* -> develop)

Title: fix(<scope>): <description>

## What
Fix for [problem description]

## Problem
[Bug description, how it manifests, impact]

## Solution
[Explanation of implemented solution]

## Testing
- [How the fix was tested]
- [Regression tests added]

## Checklist
- [ ] Bug resolved
- [ ] Regression tests added
- [ ] No side effects introduced

---

Hotfix (hotfix/* -> main)

Title: hotfix(<scope>): <critical fix>

## HOTFIX

### Issue
[Description of critical production issue]

### Root cause
[Identified cause]

### Fix
[Implemented solution]

### Impact
- Affected users: [estimate]
- Downtime: [if applicable]

### Rollback plan
[Rollback plan if needed]

## Checklist
- [ ] Fix tested in staging
- [ ] Approval for urgent deploy
- [ ] Post-deploy monitoring planned

---

Refactoring (refactor/* -> develop)

Title: refactor(<scope>): <description>

## What
Refactoring of [component/module]

## Why
- [Motivation: performance, maintainability, technical debt]

## Changes
- [Change 1]
- [Change 2]

## Impact
- **Functional**: None (behavior unchanged)
- **Performance**: [expected improvements]
- **Maintainability**: [benefits]

## Checklist
- [ ] Functional behavior unchanged
- [ ] Existing tests passing
- [ ] New tests added (if needed)

---

Documentation (docs/*)

Title: docs(<scope>): <description>

## What
Documentation update for [area]

## Changes
- [Document 1]: [change type]
- [Document 2]: [change type]

## Motivation
[Why this documentation is needed]

---

CI/CD and infrastructure

Title: ci(<scope>): <description> or chore(<scope>): <description>

## What
[Pipeline/infrastructure change]

## Changes
- [Change 1]
- [Change 2]

## Impact
- Build time: [variation]
- Deploy process: [variation]

## Testing
[How it was verified]