references/pr-template.md
# PR Template
Use this exact template structure when creating pull requests. The CI validation script (`validate-pr-description.js`) checks for these sections.
## Template
```markdown
## About PR 📝
<!-- Describe what changes you introduced and why. -->
## Preview (screenshot or recording) 🖼️
<!-- Place a screenshot or recording here (if applicable). -->
## How to test 🧪
<!-- Describe how to test these changes or what reviewers should check. -->
## Type of change 🔧
- [ ] Bug fix 🐛
- [ ] New feature ✨
- [ ] Refactor 🧹
- [ ] Improvement 📈
- [ ] Documentation 📝
- [ ] Testing 🧪
```
## Validation Rules
The CI script validates three things:
### 1. About PR Section (Required)
- **Cannot be empty** - Must contain actual content
- **HTML comments don't count** - The script strips all `<!-- ... -->` comments before checking
- If only comments remain after stripping, it's considered empty
### 2. Type of Change (Required)
- **Must check at least one** checkbox using `[x]` or `[X]`
- The script looks for patterns like `- [x] Bug fix` (case-insensitive)
### 3. Visual Proof (Conditionally Required)
Required when you select any of these types:
- Bug fix
- New feature
- Refactor
- Improvement
**Not required** for:
- Documentation
- Testing
The script detects visual proof by looking for:
- Inline images: ``
- Inline videos: `<video>` tags
- External links containing: `loom.com`, `youtube.com`, `youtu.be`, `vimeo.com`, `github.com/user-attachments/assets`, or `githubusercontent.com` URLs ending in `.png`, `.jpg`, `.jpeg`, `.gif`, `.mp4`, `.webm`
## Severity Levels
The script determines severity based on selected change types:
| Selected Type | Severity | Behavior |
|---------------|----------|----------|
| New feature | **BLOCKING** | PR cannot merge if validation fails |
| Improvement | **BLOCKING** | PR cannot merge if validation fails |
| Bug fix | WARNING | Check fails but doesn't block merge |
| Refactor | WARNING | Check fails but doesn't block merge |
| Documentation | NONE | No validation failure |
| Testing | NONE | No validation failure |
If multiple types are selected, the highest severity applies (blocking > warning > none).
## Example: Valid PR Description
```markdown
## About PR 📝
Add OAuth2 authentication support for the user login flow. This enables users to sign in with Google and GitHub accounts, reducing friction in the onboarding process and improving security by delegating password management to trusted identity providers.
## Preview (screenshot or recording) 🖼️
## How to test 🧪
1. Navigate to the login page
2. Click "Sign in with Google" or "Sign in with GitHub"
3. Complete the OAuth flow in the popup
4. Verify you're redirected back and logged in
5. Check that user profile shows the correct email and avatar
## Type of change 🔧
- [ ] Bug fix 🐛
- [x] New feature ✨
- [ ] Refactor 🧹
- [ ] Improvement 📈
- [ ] Documentation 📝
- [ ] Testing 🧪
```
## Common Validation Failures
### "About PR section is empty"
**Cause**: The About PR section contains only HTML comments or whitespace.
```markdown
## About PR 📝
<!-- Describe what changes you introduced and why. -->
```
**Fix**: Add actual content describing the change:
```markdown
## About PR 📝
Add user profile settings page allowing users to update their display name and avatar.
```
### "No type of change selected"
**Cause**: No checkbox is marked with `[x]`.
**Fix**: Check at least one type:
```markdown
- [x] New feature ✨
```
### "Screenshot or recording required for: New feature"
**Cause**: A visual-required type is selected but no visual proof detected.
**Fix**: Add one of:
- Drag/drop an image directly into the PR description (GitHub creates a link)
- Inline image: ``
- Video tag: `<video src="https://..."></video>`
- Link to Loom, YouTube, etc.
SKILL.md
---
name: create-pull-request
description: Create a pull request following the team's PR template and validation rules. Use when the user asks to create a pull request, create a PR, open a pull request, draft a PR, or prepare changes for review.
license: MIT
metadata:
author: kota
version: "1.1.0"
---
# Create Pull Request
## Preconditions
1. Verify `gh auth status` succeeds. If not, prompt user to run `gh auth login`.
2. Verify not on `main`/`master`. If so, prompt user to create a feature branch.
3. Verify no uncommitted changes. If found, prompt user to commit first (consider using `conventional-commit` skill).
4. If no upstream exists, run `git push -u origin HEAD`.
## PR Template
The PR description must follow the team's template structure. **See [references/pr-template.md](references/pr-template.md) for the full template, validation rules, and examples.**
Required sections:
1. **About PR 📝** - What changed and why (cannot be empty)
2. **Preview 🖼️** - Screenshot/recording (required for: Bug fix, New feature, Refactor, Improvement)
3. **How to test 🧪** - Testing instructions for reviewers
4. **Type of change 🔧** - Check at least one checkbox
Validation levels:
- **BLOCKING**: New feature, Improvement (PR cannot merge if validation fails)
- **WARNING**: Bug fix, Refactor
- **INFORMATIONAL**: Documentation, Testing
## Steps
### 1. Gather context
```bash
git diff main...HEAD --stat
git log main..HEAD --oneline
```
Understand: What problem does this solve? What is the impact?
### 2. Determine PR type
Identify the primary type based on changes. If multiple apply, choose the primary one.
### 3. Collect visual proof (if required)
For Bug fix, New feature, Refactor, or Improvement:
- Ask the user to provide a screenshot, recording, or link
- Verify the format is acceptable (see acceptable formats above)
- If the user cannot provide visual proof, warn them that:
- Automated validation (if present) will fail
- Manual review will require justification for missing visual proof
### 4. Draft the PR description
Use the template from [references/pr-template.md](references/pr-template.md):
```markdown
## About PR 📝
[2-3 sentences on value/impact, not implementation details]
## Preview (screenshot or recording) 🖼️
[If required: screenshot, video, or link]
## How to test 🧪
1. [Step-by-step testing instructions]
2. [What reviewers should check]
## Type of change 🔧
- [ ] Bug fix 🐛
- [ ] New feature ✨
- [ ] Refactor 🧹
- [ ] Improvement 📈
- [ ] Documentation 📝
- [ ] Testing 🧪
```
Mark the appropriate type with `[x]`.
### 5. Generate a concise title
Create a title that:
- Starts with a verb (Add, Fix, Update, Refactor, etc.)
- Is concise (< 72 characters)
- Describes the change, not the implementation
Examples:
- ✅ "Add user profile settings page"
- ✅ "Fix age validation for student dependants"
- ❌ "Update UserProfile.tsx and add new component"
### 6. Create the PR
Use the GitHub CLI to create the PR:
```bash
gh pr create --title "Your title here" --body "$(cat <<'EOF'
[Your complete PR description here]
EOF
)"
```
If creating a draft PR:
```bash
gh pr create --draft --title "Your title here" --body "$(cat <<'EOF'
[Your complete PR description here]
EOF
)"
```
### 7. Verify creation
After creation:
- Display the PR URL to the user
- If the repository has automated PR validation (e.g., `scripts/validate-pr-description.js`), note that GitHub Actions will validate the PR description
- Remind the user to review the PR checklist manually if no automated validation exists
- The PR can be edited on GitHub if any issues are found
## Validation Checklist
Verify the PR includes:
1. **About PR section** - Substantive content explaining value/impact
2. **Type of change** - At least one checkbox selected
3. **Visual proof** (if applicable) - For Bug fix, New feature, Refactor, Improvement
4. **Testing instructions** - Clear steps for reviewers
5. **Meaningful title** - Concise, verb-first description
## Notes
- Do not create PRs with empty or placeholder descriptions
- Visual proof is required for the specified types
- The PR can be edited after creation if validation fails