Pr

Pull Request Management

Reference: Linear GitHub Integration - https://linear.app/docs/github#enable-autolink

/pr - Create Pull Request

1. Pre-flight Checks:

   • Verify we're on a feature branch (not main/master)
   • Check that branch has commits ahead of base branch, if not use the /commit command to commit the changes
   • Ensure branch is pushed to remote repository
   • Confirm GitHub CLI is authenticated

2. Analyze Changes:

   • Run git log main..HEAD or git log master..HEAD to see commits
   • Run git diff main...HEAD to see all changes
   • Identify primary change type (feat, fix, chore, etc.)
   • Determine scope from affected components
   • Check for Linear issue references in commits

3. Generate PR Title:

   • Format: <type>(<scope>): <summary>
   • Use conventional commit format
   • Summarize the overall change, not individual commits
   • Keep under 72 characters

4. Build PR Description:

   • Check for .github/pull_request_template.md
   • If template exists, use as base structure
   • Generate Summary section from commit messages
   • Add Test Plan with checklist items
   • Include Linear issue links if mentioned
   • Remove template placeholders if no data available

5. Create PR:

   • Use gh pr create with title and body
   • Use heredoc for proper formatting
   • Set base branch (usually main)
   • Return PR URL for user as a markdown link

/pr check or /pr validate or /pr review - PR Validation

1. Quality Gate Checks:

   • Run project tests (detect test framework automatically)
   • Run linting and formatting checks
   • Run build/compilation if applicable
   • Check for security vulnerabilities
   • Verify all quality gates pass

2. PR Detection:

   • Check if current branch has an associated PR
   • Get PR details using gh pr view
   • If no PR exists, suggest creating one with /pr

3. Title Validation:

   • Verify title follows conventional commit format
   • Check title length (recommended: under 72 characters)
   • Ensure title accurately summarizes the changes

4. Description Completeness:

   • Check for required template sections (Summary, Test Plan)
   • Verify description provides sufficient context
   • Look for linked issues or related work
   • Ensure test plan is actionable

5. Metadata Check:

   • Verify assignees are set (usually the author)
   • Check for appropriate labels based on change type
   • Review milestone assignment if applicable
   • Confirm reviewers are requested

6. CI/CD Status:

   • Check status of required checks (tests, linting, build)
   • Identify any failing checks that block merge
   • Show check details and failure reasons
   • Suggest fixes for common check failures

/pr ready - Mark PR Ready for Review

1. PR Status Check:

   • Get current PR details using gh pr view
   • Check if PR is in draft status
   • Verify PR is associated with current branch
   • Confirm PR has not been merged or closed

2. Quality Validation:

   • Run validation checks to ensure completeness
   • Ensure all required template sections are filled
   • Verify conventional commit title format
   • Check that description provides adequate context

3. CI/CD Verification:

   • Check status of all required checks
   • Wait for in-progress checks to complete (with timeout)
   • Identify any failing checks that block review
   • Ensure no merge conflicts exist

4. Reviewer Assignment:

   • Detect appropriate reviewers based on:
     • Code owners (CODEOWNERS file)
     • Changed file patterns
     • Team assignments
     • Previous reviewers on similar changes
   • Request reviews from selected team members
   • Assign PR to author if not already assigned

5. Ready Status Update:

   • Remove draft status if currently draft
   • Apply "ready-for-review" label
   • Add change-type labels (feature, bugfix, etc.)
   • Update PR status to ready for review

Project Quality Checks

Documentation-Based Quality Gates

1. Check for CONTRIBUTING.md:

   • Look for .github/CONTRIBUTING.md or CONTRIBUTING.md in project root
   • Parse quality check commands from documentation
   • Extract test, lint, build, and security commands
   • Follow project-specific guidelines

2. Fallback to README.md:

   • If no CONTRIBUTING.md found, check README.md
   • Look for development setup and testing sections
   • Extract available quality check commands
   • Use common patterns for different project types

3. Auto-Detection Fallback:

   • If no documentation found, auto-detect based on project structure
   • Check for common config files (package.json, Cargo.toml, go.mod, etc.)
   • Use standard commands for detected project types

Quality Check Execution

# 1. Check for project documentation
if [ -f "CONTRIBUTING.md" ]; then
  # Parse commands from CONTRIBUTING.md
elif [ -f ".github/CONTRIBUTING.md" ]; then
  # Parse commands from .github/CONTRIBUTING.md
elif [ -f "README.md" ]; then
  # Parse commands from README.md
else
  # Auto-detect based on project structure
fi

# 2. Execute quality checks in order
# - Tests (from documentation or auto-detected)
# - Linting (from documentation or auto-detected)
# - Build (from documentation or auto-detected)
# - Security (from documentation or auto-detected)

Documentation Parsing

Look for common patterns in documentation:

• Test commands: npm test, yarn test, pytest, cargo test, go test
• Lint commands: npm run lint, flake8, cargo clippy, gofmt
• Build commands: npm run build, cargo build, go build, mvn compile
• Security commands: npm audit, pip-audit, cargo audit

Project Type Detection

# Detect project type for fallback commands
if [ -f "package.json" ]; then
  # Node.js project
elif [ -f "Cargo.toml" ]; then
  # Rust project
elif [ -f "go.mod" ]; then
  # Go project
elif [ -f "pom.xml" ]; then
  # Maven project
elif [ -f "build.gradle" ]; then
  # Gradle project
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  # Python project
fi

PR Quality Gates

✅ Title Format

• Follows conventional commit format
• Under 72 characters
• Clear and descriptive
• Matches primary change type

✅ Description Quality

• Has summary of changes
• Includes test plan with checkboxes
• Links to related issues
• Provides sufficient context
• No template placeholders left unfilled

✅ Metadata Complete

• Author assigned to PR
• Appropriate labels applied
• Reviewers requested
• Milestone set (if required)

✅ CI/CD Passing

• All required checks pass
• No merge conflicts
• Branch is up to date with base
• Build succeeds

✅ Content Quality

• Commits follow conventional format
• No WIP or debugging commits
• Logical commit structure
• Changes are focused and related

Linear GitHub Integration

Issue Reference Format

IMPORTANT: Always use full markdown URL format for Linear issue references:

# Correct - Full markdown URL (preferred)
Closes [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)

# Avoid - Just the ID (less informative)
Closes PLTFRM-123

Fetching Issue Details

When a Linear issue ID is detected in commits, fetch the issue details using Linearis CLI:

linearis issues read PLTFRM-123

Use the response to build the full markdown URL with title.

Auto-linking Setup

• Use magic words like "Closes", "Fixes", "Resolves" followed by the full markdown link
• Linear will auto-link and close issues when GitHub integration is enabled

Commit Message Format

feat(auth): add JWT token validation middleware

- Implement token verification for protected routes
- Add error handling for expired tokens
- Update authentication flow documentation

Closes [PLTFRM-123: Add JWT validation](https://linear.app/cloudwalk/issue/PLTFRM-123/add-jwt-validation)

PR Description Format

## Related Issues

Closes [PLTFRM-123: Add JWT validation](https://linear.app/cloudwalk/issue/PLTFRM-123/add-jwt-validation)

## Summary

- Add JWT authentication middleware for API routes
- Implement token validation and error handling
- Update authentication flow documentation

## Test Plan

- [ ] Verify protected routes require valid JWT
- [ ] Test expired token error handling
- [ ] Confirm authentication flow works end-to-end
- [ ] Run existing authentication test suite

• ❌ Never create PR from main/master branch
• ❌ Never create PR without committed changes
• ❌ Never push to main/master directly
• ✅ Always verify branch is ahead of base
• ✅ Always push branch before PR creation
• ✅ Always use conventional commit format for title
• ✅ Include Linear issue references for auto-linking
• ✅ Run quality checks before PR creation

Command Output Formats

/pr - PR Creation Report

# 🚀 PR Created Successfully

**PR**: #[number] - [title](github-pr-url)
**Branch**: [feature-branch] → [base-branch]
**URL**: [github-pr-url]
**Status**: [Draft | Open]

## 📝 Changes Summary

- [x] commits ahead of base branch
- [x] files changed
- Primary change type: [feat/fix/chore/etc.]

## 🎯 Next Steps

- [ ] Run `/pr check` to validate quality
- [ ] Run `/pr ready` when ready for review
- [ ] Monitor CI/CD checks

/pr check - Validation Report

# 🔍 PR Validation Report

**PR**: #[number] - [title](github-pr-url)
**Branch**: [feature-branch] → [base-branch]
**Author**: @[username]
**Status**: [Draft|Open|Ready for Review]
**URL**: [github-pr-url]

## ✅ Quality Gates

- **Tests**: [✅ Pass | ❌ Fail] ([X/Y] passed)
- **Linting**: [✅ Pass | ❌ Fail]
- **Build**: [✅ Pass | ❌ Fail]
- **Security**: [✅ Pass | ❌ Warn | ❌ Fail]

## 📊 Validation Results

- **Title Format**: [✅/❌] Conventional commit format
- **Description**: [✅/❌] Complete and informative
- **Metadata**: [✅/❌] Assignees, labels, reviewers
- **CI/CD**: [✅/❌] All checks passing

## 🚨 Issues Found

- [List specific issues that need fixing]

## 💡 Recommendations

- [Specific improvements to make]

/pr ready - Ready for Review Report

# 🎯 PR Ready for Review

**PR**: #[number] - [title](github-pr-url)
**Branch**: [feature-branch] → [base-branch]
**Author**: @[username]
**URL**: [github-pr-url]

## ✅ Readiness Validation

- **Content Quality**: [✅ Ready | ⚠️ Needs attention]
- **CI/CD Status**: [✅ All passing | ⚠️ Some failing | 🔄 In progress]
- **Review Setup**: [✅ Reviewers assigned | ⚠️ Needs reviewers]
- **Draft Status**: [✅ Ready for review | 🔄 Converted from draft]

## 👥 Reviewers Assigned

**Required** (CODEOWNERS):

- @[required-reviewer1] - [ownership reason]

**Suggested**:

- @[suggested-reviewer1] - [domain expertise]

## 🏷️ Labels Applied

- `ready-for-review`
- `[change-type]` (feature/bugfix/chore)
- `[area]` (frontend/backend/docs)

## 🔗 PR Details

**URL**: [github-pr-url]
**Estimated Review Time**: [based on change size]

Basic Usage

Create PR

# Create PR with auto-detected title and description
/pr

# Create PR with custom title
/pr "feat(auth): add OAuth2 integration"

# Create PR with specific base branch
/pr --base develop

Validate PR

# Run all quality checks and validation
/pr check

# Alternative commands (same functionality)
/pr validate
/pr review

Mark Ready for Review

# Mark PR as ready for review
/pr ready

# Mark ready with specific reviewers
/pr ready --reviewers @user1,@user2

# Mark ready with priority
/pr ready --priority high

Complete Workflow

# 1. Create and commit changes
git add .
git commit -m "feat(auth): add JWT validation

- Implement token verification
- Add error handling
- Update documentation

Closes ENG-123"

# 2. Create PR
/pr

# 3. Validate quality
/pr check

# 4. Mark ready for review
/pr ready

Arguments: $ARGUMENTS

• /pr - Create pull request (optional: title override, base branch)
• /pr check|validate|review - Run quality checks and validation
• /pr ready - Mark PR ready for review (optional: reviewers, priority)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.