/create-pr-from-spec

name: create-pr-from-spec
description: "Create GitHub Pull Request from specification using pull_request_template.md. Use when: spec needs to be converted to PR, spec is ready for review/merge, need to automate PR creation from specification file with template-based body and title."
allowed-tools: Read, Grep, Glob, Bash

Create Pull Request from Specification

Create a GitHub Pull Request for a specification using the pull_request_template.md template located at `${workspaceFolder}/.github/pull_request_template.md`.

Overview

This skill automates the creation of GitHub Pull Requests directly from specifications. It follows a structured process:

1. Analyzes the specification template requirements 2. Creates a draft PR with the target branch 3. Verifies no duplicate PRs exist 4. Updates PR body and title with template-compliant content 5. Marks PR as ready for review 6. Automatically assigns to the creator 7. Returns PR URL to user

**Key Benefits:**

• ✅ Automated PR creation from specifications
• ✅ Template-compliant PR body and title
• ✅ Duplicate PR prevention
• ✅ Auto-assignment to creator
• ✅ Streamlined spec-to-PR workflow

When to Use

Use this skill when:

1. **Specification is ready to merge** - Convert finalized spec to PR 2. **Need automated PR creation** - Avoid manual PR drafting 3. **Template compliance required** - Ensure PR follows pull_request_template.md 4. **Multiple PRs from specs** - Batch process specifications into PRs 5. **Team collaboration** - Share specs as PRs for review

**Trigger phrases:**

• "Create pull request from spec"
• "Convert spec to PR"
• "Open PR for specification"
• "Submit spec as pull request"
• "Automate PR creation"

Instructions

Prerequisites

Before using this skill, ensure:

• Specification file is finalized and ready for review
• Target branch is specified (e.g., `main`, `develop`)
• `.github/pull_request_template.md` exists in the repository
• You have write access to create PRs

Step-by-Step Process

**1. Analyze specification template**

• Extract requirements from `${workspaceFolder}/.github/pull_request_template.md`
• Use search tool to parse template sections and placeholders

**2. Create pull request draft**

• Use `create_pull_request` tool to create draft PR to target branch
• First verify no existing PR exists using `get_pull_request` to prevent duplicates
• If PR already exists, stop and report to user

**3. Get pull request changes**

• Use `get_pull_request_diff` tool to analyze differences
• Verify code changes are correct before updating

**4. Update pull request**

• Use `update_pull_request` tool to populate PR body and title
• Incorporate template sections from step 1
• Ensure all required fields are filled

**5. Mark ready for review**

• Use `update_pull_request` tool to change state from draft to ready for review
• Verify PR is no longer in draft mode

**6. Assign pull request**

• Use `get_me` to retrieve current user information
• Use `update_issue` tool to assign PR to creator

**7. Return pull request URL**

• Provide user with clickable PR URL
• Include summary of PR contents

Examples

Example 1: Basic PR Creation

Input: Create PR from spec to main branch
Process:
  1. Analyze pull_request_template.md
  2. Create draft PR to main
  3. Check for existing PRs
  4. Update PR title: "feat: [Feature Name from Spec]"
  5. Update PR body with template sections
  6. Mark as ready for review
  7. Assign to creator
Output: https://github.com/user/repo/pull/123

Example 2: Template-Compliant PR

PR Title: feat: Implement user authentication system

PR Body:
## Description
Implements JWT-based authentication with token refresh mechanism

## Related Issue
Closes #456

## Changes
- Added JWT middleware
- Implemented token validation
- Added refresh token endpoint

## Testing
- Unit tests for auth middleware
- Integration tests for token endpoints

## Checklist
- [x] Tests pass
- [x] Documentation updated
- [x] No breaking changes

Example 3: Duplicate Prevention

Input: Create PR from spec
Check: PR for current branch already exists?
  → Yes: Report error, don't create duplicate
  → No: Proceed with PR creation
Output: "PR already exists at https://github.com/user/repo/pull/789"

Requirements

• Single pull request for the complete specification
• Clear title and body identifying the specification/feature
• Pull request body follows pull_request_template.md structure
• Verification that no duplicate pull requests exist
• PR automatically assigned to creator
• No draft PRs left behind

Success Criteria

• ✅ PR created without errors
• ✅ PR body follows pull_request_template.md structure
• ✅ PR title clearly identifies the specification/feature
• ✅ No duplicate PRs exist for the branch
• ✅ PR assigned to creator
• ✅ PR URL returned to user
• ✅ PR is ready for review (not in draft)

Constraints and Warnings

⚠️ **Important:**

• PR creation requires write access to repository
• Target branch must exist before PR creation
• Template file must exist at `.github/pull_request_template.md`
• Cannot create PR without valid branch target
• Duplicate PRs will be detected and rejected
• PR assignment requires valid GitHub user

🚫 **Limitations:**

• Does not perform code review automatically
• Does not trigger CI/CD pipelines
• Does not merge PRs automatically
• Cannot modify existing code, only PR metadata

Best Practices

1. **Verify before creating** - Always review specification before converting to PR 2. **Use descriptive titles** - PR titles should clearly indicate feature/fix purpose 3. **Complete template** - Ensure all required template sections are filled 4. **Link related issues** - Include issue references in PR body 5. **Test first** - Ensure all tests pass before creating PR 6. **Team review** - Get team approval before marking ready for review 7. **Clean git history** - Ensure commits are clean and well-documented

Tools Used

• `sear