PR Management Skill

Create and update pull requests with automated analysis, conventional commits, and project-aware checks.

Quick Start

# Check if PR exists for current branch
gh pr view 2>/dev/null && echo "PR exists - will update" || echo "No PR - will create"

# View current changes
git status && git diff --stat

Instructions

Step 1: Determine Workflow

First, check if a PR already exists:

gh pr view

• No PR exists: Follow "Creating a New PR" workflow
• PR exists: Follow "Updating an Existing PR" workflow

---

Creating a New PR

Step 2: Analyze Changes

Run these commands in parallel to understand the current state:

# Current status
git status

# All changes (staged + unstaged)
git diff HEAD

# Recent commits on this branch
git log --oneline -10

# Identify affected Nx projects
yarn nx affected --base=origin/development --head=HEAD --plain

Identify from the output:

• Files modified, added, or deleted
• Purpose and scope of changes
• Affected projects: backend, storefront, core-api, admin-dashboard, shared-types

Step 3: Determine Change Type

Classify using conventional commit types:

Type	Description
feat	New feature (non-breaking)
fix	Bug fix
refactor	Code restructuring (no functional changes)
docs	Documentation updates
ci	CI/CD or tooling changes
chore	Maintenance tasks
test	Adding or updating tests
breaking	Changes that break existing functionality

Step 4: Create Feature Branch (if needed)

If on development or main, create a feature branch:

# Branch naming: <type>/<short-description>
git checkout -b feat/add-product-search
git checkout -b fix/cart-total-calculation
git checkout -b refactor/user-service-cleanup

Step 5: Run Quality Validation Checks

CRITICAL: Run all quality checks on affected projects before committing. All checks must pass.

# Type check affected projects
yarn nx affected --target=type-check --base=origin/development --head=HEAD

# Lint affected projects
yarn nx affected --target=lint --base=origin/development --head=HEAD

# Run tests on affected projects
yarn nx affected --target=test --base=origin/development --head=HEAD

All checks must pass before proceeding. Fix any issues:

• TypeScript errors must be resolved (no any types)
• Linting errors must be fixed (follow project conventions)
• All tests must pass (no failing tests)

If any check fails, do not proceed with commit and PR creation.

Step 6: Stage and Commit

# Stage changes
git add <files>
# or
git add .

# Commit with conventional format
git commit -m "<type>(<scope>): <description>"

Commit message guidelines:

• Use imperative mood: "add feature" not "added feature"
• Keep subject under 72 characters
• Optional scope: feat(storefront): add product filtering
• Reference issues: fix(backend): resolve cart error (#123)

For multiple logical changes, create separate commits.

Step 7: Push to Remote

git push -u origin <branch-name>

Step 8: Create Pull Request

Use this command with the filled template:

gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
## Description

<!-- Write 1-2 sentences summarizing the changes -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Refactoring (no functional changes)
- [ ] Documentation update
- [ ] CI/CD or tooling changes

## Affected Projects

- [ ] `backend` (MedusaJS)
- [ ] `storefront` (Next.js)
- [ ] `core-api` (NestJS)
- [ ] `admin-dashboard`
- [ ] `shared-types`
- [ ] Root/workspace configuration

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed

## Checklist

- [ ] Code follows project conventions (see CLAUDE.md)
- [ ] Self-review completed
- [ ] No `any` types introduced
- [ ] No console.log statements left in code
- [ ] Linting passes (`yarn lint`)
- [ ] Type checking passes (`yarn type-check`)
- [ ] Tests pass (`yarn test`)

## Related Issues

<!-- Link issues: Fixes #123, Closes #456 -->

## Screenshots (if applicable)

<!-- Add screenshots for UI changes -->
EOF
)"

Step 9: Fill the Template

When creating the PR body:

1. Description: Summarize the "why" behind the changes
2. Type of Change: Check boxes matching Step 3 classification
3. Affected Projects: Check based on file paths:
   • apps/backend/ → backend
   • apps/storefront/ → storefront
   • apps/core-api/ → core-api
   • apps/admin-dashboard/ → admin-dashboard
   • Other → Root/workspace
4. Testing: Mark what was performed
5. Checklist: Verify each item
6. Related Issues: Link GitHub issues

---

Updating an Existing PR

Step 1: Check PR Status

# View PR details
gh pr view

# Check CI status
gh pr checks

Step 2: Analyze New Changes

# Changes since last push
git diff origin/<branch-name>

# Commits to be pushed
git log origin/<branch-name>..HEAD --oneline

Step 3: Run Quality Validation Checks

CRITICAL: Run all quality checks on affected projects before pushing. All checks must pass.

# Type check affected projects
yarn nx affected --target=type-check --base=origin/development

# Lint affected projects
yarn nx affected --target=lint --base=origin/development

# Run tests on affected projects
yarn nx affected --target=test --base=origin/development

All checks must pass before proceeding. Fix any issues:

• TypeScript errors must be resolved (no any types)
• Linting errors must be fixed (follow project conventions)
• All tests must pass (no failing tests)

If any check fails, do not proceed with pushing updates.

Step 4: Push Updates

git add <files>
git commit -m "<type>(<scope>): <description>"
git push

Step 5: Update PR Details (if needed)

# Update title
gh pr edit --title "<new-title>"

# Update description
gh pr edit --body "$(cat <<'EOF'
## Description
[Updated description with new changes]

## Type of Change
[Updated checkboxes]

...rest of template...
EOF
)"

# Add comment explaining updates
gh pr comment --body "Updated PR:
- Fixed review feedback on authentication
- Added missing tests
- Updated documentation"

Step 6: Manage PR State

# Convert draft to ready
gh pr ready

# Mark as draft again
gh pr ready --undo

# Request re-review
gh pr edit --add-reviewer @username

---

Examples

Creating a Feature PR

# 1. Analyze
git status
git diff HEAD
yarn nx affected --base=origin/development --plain

# 2. Create branch
git checkout -b feat/add-product-filtering

# 3. Run quality validation checks
yarn nx affected --target=type-check --base=origin/development
yarn nx affected --target=lint --base=origin/development
yarn nx affected --target=test --base=origin/development

# 4. Commit
git add apps/storefront/src/modules/products/
git commit -m "feat(storefront): add product filtering by category"

# 5. Push
git push -u origin feat/add-product-filtering

# 6. Create PR
gh pr create --title "feat(storefront): add product filtering by category" \
  --body "## Description
Adds category-based filtering to the product listing page.

## Type of Change
- [x] New feature (non-breaking change that adds functionality)

## Affected Projects
- [x] \`storefront\` (Next.js)

## Testing
- [x] Manual testing performed

## Checklist
- [x] Code follows project conventions
- [x] Linting passes
- [x] Type checking passes"

Updating After Review Feedback

# 1. Make fixes
git add .
git commit -m "fix(storefront): address review feedback on filtering"

# 2. Run quality validation checks
yarn nx affected --target=type-check --base=origin/development
yarn nx affected --target=lint --base=origin/development
yarn nx affected --target=test --base=origin/development

# 3. Push
git push

# 4. Comment
gh pr comment --body "Addressed review feedback:
- Fixed filter state reset issue
- Added loading indicator"

---

Best Practices

• ALWAYS run quality checks: Run type-check, lint, and test before every commit and push
• All checks must pass: Never create or update a PR with failing quality checks
• Use scoped commits: feat(storefront): helps identify affected areas
• One PR, one purpose: Keep PRs focused and reviewable
• Draft PRs for WIP: Use gh pr create --draft for incomplete work
• Document breaking changes: Include migration steps in description
• Link issues: Always reference related GitHub issues
• Fix issues immediately: If quality checks fail, fix them before proceeding

Validation Checklist

Before finalizing the PR:

• Branch name follows <type>/<description> convention
• All commits use conventional commit format
• yarn nx affected --target=lint passes
• yarn nx affected --target=type-check passes
• yarn nx affected --target=test passes
• PR title matches main commit message
• Description explains the "why"
• Correct checkboxes selected in template
• Related issues are linked