Pull Request Conventions

This skill teaches how to create and manage pull requests for this codebase. Follow these conventions for consistent, reviewable PRs that pass CI validation.

When to Use This Skill

• Creating a new pull request
• Writing PR titles and descriptions
• Preparing changes for review
• Understanding PR workflows and requirements
• Linking PRs to issues

PR Title Format

PR titles must follow the same format as commit messages:

<type>(<scope>): <gitmoji> <subject>

Structure Rules

1. Type: Required, lowercase, from allowed types
2. Scope: Required, lowercase, from allowed scopes
3. Gitmoji: Required, emoji at start of subject
4. Subject: Required, lowercase, imperative mood, no period

Valid Types

Valid Scopes

Examples

✅ Good PR titles:

feat(lexico): ✨ add user profile page
fix(caelundas): 🐛 correct aspect angle calculation
docs(codebase): 📝 update contributing guide
chore(dependencies): ⬆️ upgrade react to v19
refactor(lexico-components): ♻️ simplify button variants

❌ Bad PR titles:

feat(lexico): add user profile page           # Missing gitmoji
feat(lexico): ✨ Added profile page.           # Wrong tense, period
Add new feature                                # Missing type, scope, gitmoji
fix: 🐛 fix bug                               # Missing scope

See commit-code skill for complete formatting rules.

PR Description

Write clear, comprehensive descriptions that help reviewers understand changes. The PR template provides the standard structure.

Recommended Structure

## 🌰 Summary

<!-- Brief description of what this PR does (1-2 sentences) -->

## 📝 Details

- <!-- List of specific changes made -->

## 🧪 Testing

1. <!-- How to manually verify these changes work correctly -->

## 🔗 Related

- <!-- Link any relevant documentation or related resources like internal documentation, GitHub issues/pull requests -->

Description Guidelines

Step-by-Step Workflow

1. Create Feature Branch

Branch name must follow conventions. See checkout-branch skill.

# Create branch from main
git checkout main
git pull origin main
git checkout -b feat/lexico-user-profile

2. Make Changes and Commit

Commits must follow conventions. See commit-code skill.

# Stage and commit changes
git add .
git commit -m "feat(lexico): ✨ add user profile component"

3. Push Branch

git push -u origin feat/lexico-user-profile

4. Create Pull Request

Using GitHub CLI (preferred)

gh pr create \
  --title "feat(lexico): ✨ add user profile page" \
  --assignee @me \
  --body "## 🌰 Summary

Adds a user profile page where users can view and edit their information.

## 📝 Details

- Add UserProfile component
- Add profile API endpoint
- Add profile route to router

## 🧪 Testing

\`\`\`bash
nx run lexico:vitest
nx run lexico:develop  # Navigate to /profile
\`\`\`

## 🔗 Related

- Closes #123"

5. Address Review Feedback

# Make additional commits for feedback
git commit -m "fix(lexico): 🐛 address review feedback"
git push

6. Merge PR

After approval, merge using the GitHub UI or CLI:

gh pr merge --squash --delete-branch

CI Requirements

All PRs must pass these checks before merging:

There is no lint, format, or clean target in this workspace. nx affected --target=lint exits 0 printing "No tasks were run", so it is a check that passes without checking anything — always name a real target.

Run locally before pushing:

# Run all checks on affected projects
nx affected --target=lint-code --configuration=write --base=main
nx affected --target=lint-code --configuration=check --base=main
nx affected --target=vitest --configuration=coverage --base=main

Draft PRs

Use draft PRs for work in progress:

# Create draft PR
gh pr create --draft --assignee @me --title "feat(lexico): ✨ [WIP] add user profile"

# Mark ready for review when complete
gh pr ready

Linking Issues and Documentation

Reference issues and relevant documentation in the PR description:

Issues

Documentation

Include relevant links to help reviewers understand context:

• Internal docs: links to AGENTS.md, SKILL.md, planning files, or ADRs
• External docs: library documentation, RFCs, specifications
• Related PRs: links to dependent or prerequisite pull requests

Assignees

Always assign PRs to yourself:

gh pr create --assignee @me

Labels

Validate Conventions checks that labels agree with the title: exactly one type:* label matching the title's type, one scope:* label per scope named in the title (no extras), exactly one source:* label (source:agent or source:human) declaring who opened the pull request, and no do-not-merge label. Set them at creation time rather than waiting for the reconciliation step to backfill them:

gh pr create --label type:feat --label scope:lexico --label source:human

See the triage-integration skill for the full label vocabulary, the reconciliation step that creates missing labels on opened/reopened, and how to fix each metadata failure.

Review Requests

Request reviews from appropriate team members:

gh pr create --reviewer JimmyPaolini

Updating PR Branch

Keep your branch up to date with main:

If you plan to rebase and force-push, run backup-code first to create a recoverable checkpoint.

# Update from main
git fetch origin main
git rebase origin/main
git push --force-with-lease

Or use GitHub's "Update branch" button in the PR UI.

Squash Merging

This codebase uses squash merging by default:

• All commits in the PR become a single commit on main
• PR title becomes the commit message
• Keep PR title clean and following conventions
• The title is the only thing semantic-release reads — every commit's own type is discarded once squashed. Pick the title's type and scopes to already cover every commit on the branch; see commit-code's Release Significance section for the type-to-bump mapping and the pull-request-release-significance check that enforces it

Pre-Flight Checklist

Before creating the PR, verify:

• Branch name follows <type>/<scope>-<description> format
• All changes are committed and pushed to remote
• Title follows <type>(<scope>): <gitmoji> <subject> format (max 128 chars)
• Subject uses imperative mood and lowercase after gitmoji
• Description includes Summary, Details, and Testing sections
• Related issues and documentation are linked in the Related section
• The title's type and scopes are at least as release-significant as every commit on the branch — see Release Significance
• Local CI checks pass: nx affected --target=lint-code --configuration=check --base=main && nx affected --target=vitest --configuration=coverage --base=main

Common Patterns

Feature PR

Title: feat(lexico): ✨ add dictionary search autocomplete

## 🌰 Summary

Adds autocomplete suggestions to the dictionary search input.

## 📝 Details

- Add SearchAutocomplete component
- Integrate with search API for suggestions
- Add keyboard navigation support
- Add loading and empty states

## 🧪 Testing

```bash
nx run lexico:vitest
nx run lexico:develop
```

1. Navigate to search page and type a query.

## 🔗 Related

- Closes #234

Bug Fix PR

Title: fix(caelundas): 🐛 correct timezone offset in ephemeris

## 🌰 Summary

Fixes incorrect timezone handling for ephemeris calculations near DST boundaries.

## 📝 Details

- Use moment-timezone for DST-aware calculations
- Add edge case handling for DST transitions
- Add regression tests

## 🧪 Testing

```bash
nx run caelundas:vitest:unit
nx run caelundas:vitest:integration
```

## 🔗 Related

- Fixes #456

Documentation PR

Title: docs(codebase): 📝 add contributing guide

## 🌰 Summary

Adds comprehensive CONTRIBUTING.md with setup instructions and guidelines.

## 📝 Details

- Add CONTRIBUTING.md
- Update README.md with link to contributing guide
- Add development setup section

## 🧪 Testing

1. Review the documentation changes in the PR diff.

## 🔗 Related

- <!-- No related issues or documentation links -->

Dependency Update PR

Title: chore(dependencies): ⬆️ upgrade tanstack router to v1.50

## 🌰 Summary

Updates TanStack Router to latest version with bug fixes.

## 📝 Details

- Upgrade @tanstack/react-router from 1.45.0 to 1.50.0
- Update peer dependencies
- Fix breaking changes in route definitions

## 🧪 Testing

```bash
nx run lexico:vitest
nx run lexico:develop
```

1. All routes should work as before.

## 🔗 Related

- <!-- No related issues or documentation links -->

Troubleshooting

If a rebase or force-push update goes wrong, use restore-code to recover from your backup artifact.

Quick Reference

# Create branch
git checkout -b <type>/<scope>-<description>

# Create PR with GitHub CLI
gh pr create --title "<type>(<scope>): <gitmoji> <subject>" --assignee @me --body "..."

# Run CI checks locally
nx affected --target=lint-code --configuration=check --base=main &&
  nx affected --target=vitest --configuration=coverage --base=main

# Update branch
git fetch origin main && git rebase origin/main && git push --force-with-lease

# Merge PR
gh pr merge --squash --delete-branch

Resources

• PR template — Default PR description template
• commit-code skill — Commit and PR title format
• checkout-branch skill — Branch naming conventions
• triage-integration skill — Diagnosing failing CI checks on a PR
• backup-code — Safety checkpoint before history rewrite
• restore-code — Recovery workflow after failed branch update
• Conventional Commits
• Gitmoji