pr-create

name	pr-create
description	Creates GitHub pull requests with properly formatted titles that pass the check-pr-title CI validation. Use when creating PRs, submitting changes for review, or when user says /pr, /pr-create, or asks to create a pull request.
user-invocable	true
allowed-tools	["Bash","Read","Grep","Glob"]

PR Create

Purpose

Creates GitHub pull requests with conventional commit-style titles and structured bodies. Follows the project's git workflow conventions from docs/contributing/git-workflow.md.

Quick Reference

• Creates: GitHub PR via gh pr create
• Requires: GitHub CLI installed and authenticated, committed changes on a feature branch
• Stop hook: task claude:validate-skill -- --skill pr-create

Prerequisites

Before creating a PR, verify:

1. gh CLI installed: gh --version - if missing: brew install gh
2. gh CLI authenticated: gh auth status - if not: gh auth login

PR Title Format

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

Types

Type	Use for
feat	New features
fix	Bug fixes
chore	Maintenance, refactoring
docs	Documentation
test	Test changes
perf	Performance improvements
ci	CI/CD changes

Scopes

• app - Application service
• consensus - Consensus interactions
• config - Configuration
• contracts - Contract wrappers
• report - Reporting/notifications
• infra - Infrastructure/Terraform
• skills - Claude Code skills

Title Rules

1. Max 50 characters
2. Capitalized first letter after colon
3. No period at the end
4. Be specific - avoid "improve", "enhance", "update"
5. NO AI ATTRIBUTION - STRICTLY FORBIDDEN

AI Attribution Policy

COMPLETE VIOLATION - Never include ANY of the following in PR titles, bodies, or commits:

• Co-Authored-By: Claude, Co-Authored-By: GPT, or any AI name
• 🤖 emoji or any AI-related emojis
• "Generated by", "Created with", or similar phrases
• Any reference to AI tools (Claude, ChatGPT, Copilot, etc.)

PRs and commits must appear as human-authored work. This is a strict project requirement.

Changelog Categorization

PRs fall into two categories based on their audience. The description should make this obvious for future changelog review.

Important: The type alone doesn't determine this. Any type can be changelog-worthy depending on impact.

Changelog-worthy (user-facing)

Description focuses on user/product impact:

• What capability was added or fixed?
• How does this affect the product or end users?

Examples:

feat(consensus): Add validator ban detection
→ Adds monitoring for validator bans. Reports via Slack with reason and duration.

docs: Add API authentication guide
→ Documents how to authenticate with the API.

chore(deps): Upgrade axios to fix security vulnerability
→ Fixes CVE-2024-XXXX in axios affecting API requests.

Internal/dev-only (not in changelog)

Description focuses on developer/process impact:

• What tooling or process changed?
• No user-facing impact

Examples:

chore(skills): Add AI attribution validation
→ Adds automated validation to catch AI attribution in PRs.

docs: Update development setup instructions
→ Clarifies Node version requirements for contributors.

ci: Add parallel test execution
→ Speeds up CI pipeline by running tests in parallel.

Network Labels

PRs can include network labels to trigger auto-deploy on merge via the release workflow:

Label	Network	Description
asimov-phase4	asimov-phase4	Main testnet - production
bradbury	bradbury	Secondary testnet - staging

Behavior:

• No label = release created (version bump, Docker image, GitHub Release) but deploy is skipped
• One label = release + deploy to that network
• Multiple labels = release + deploy to each labeled network

Labels are optional. Omitting them means the release is created without triggering deployment. Users can manually deploy later via the deploy workflow.

PR Body Template

PR bodies MUST follow the template in .github/PULL_REQUEST_TEMPLATE.md:

## Description

[2-3 sentences summarizing what changed]

## Release Notes

[User-facing summary for the changelog. Focus on what changed from the user's perspective.
Use bullet points for multiple changes.]

## Types of Changes

- [ ] 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 not work as expected)
- [ ] Chore (maintenance tasks, refactoring, or non-functional changes)

## Checklist

- [ ] My code follows the code style of this project
- [ ] I have added the necessary documentation (if appropriate)
- [ ] I have added tests (if appropriate)
- [ ] Lint and unit tests pass locally with my changes

Fill in Description and Release Notes, mark the appropriate Type with [x], and check applicable Checklist items.

Release Notes are extracted by the release workflow and used as GitHub Release notes and CHANGELOG.md entries. Write them for end users, not developers. Example:

## Release Notes

- Added validator ban detection with Slack notifications
- Fixed transaction timeout handling during high-load periods

User Review Step

Before creating the PR, present it to the user for review:

## PR Preview

**Title:** feat(consensus): Add validator ban detection
**Labels:** asimov-phase4

**Body:**
## Description

Adds monitoring for validator bans on the network.
When a validator is banned, the system detects and reports via Slack.

## Release Notes

- Added validator ban detection with Slack notifications

## Types of Changes

- [ ] Bug fix
- [x] New feature
...

---
Any changes I should make?

Wait for user confirmation:

• If user says "no" or confirms → create the PR
• If user requests changes → incorporate feedback and show again

Automation

See skill.yaml for the full procedure and patterns. See sharp-edges.yaml for common failure modes.