creating-pull-request

Autonomous Mode

When user says "answer yourself the questions", "responda você mesmo as perguntas", or any equivalent instruction to avoid interactive prompts:

• DO NOT call AskUserQuestion at any step
• Derive all answers from git context:
  • PR Type: infer from commit message prefixes (fix → Bug fix, feat → New feature, refactor → Refactor, etc.)
  • Jira link: extract the ticket number from the branch name and resolve {{company_name}} per the "Inferring company_name" section below
  • Additional links: default to "None"
  • Checklist: mark "Tests run locally" and "Code reviewed line by line" as checked by default; omit items you cannot verify from context
  • Impact: default to no special impacts unless commit messages indicate otherwise
  • Reviewer notes: generate based on the most complex or risky changes detected in the diff
• Proceed directly to Step 5 (Generate PR Description) after completing Steps 1–2
• Still execute Step 6 (Create PR) normally

Inferring company_name

The Jira URL has the form https://{{company_name}}.atlassian.net/browse/{TICKET}. The company_name is the Atlassian workspace subdomain (e.g. acme for acme.atlassian.net). Resolve it in this order — stop at the first match:

1. Cached value: read ~/.claude/.creating-pr-config (a simple KEY=VALUE file). If JIRA_COMPANY=... is set, use it.
2. Repository hints: search the repo for an existing Atlassian reference:

   grep -rEo '[a-z0-9-]+\.atlassian\.net' \
     --include='*.md' --include='*.yml' --include='*.yaml' \
     --include='*.json' --include='*.properties' . | head -5

   If a single distinct subdomain appears, use it.
3. Recent PR descriptions: gh pr list --state all --limit 20 --json body | grep -Eo '[a-z0-9-]+\.atlassian\.net'. If a single subdomain dominates, use it.
4. Ask the user once (interactive mode only): "What is your company's Atlassian subdomain? (e.g. acme for acme.atlassian.net)". After receiving an answer, persist it:

   mkdir -p ~/.claude && echo "JIRA_COMPANY={value}" >> ~/.claude/.creating-pr-config

5. Autonomous mode fallback: if no value can be inferred and questions are disabled, leave the placeholder {{company_name}} literally in the PR body and warn the user in the post-creation summary so they can edit it.

Detecting base branches

This skill uses two base branches:

• Diff base (Step 1): the branch your feature branched off from. Detect via gh repo view --json defaultBranchRef -q .defaultBranchRef.name, falling back to checking git rev-parse --verify main then master.
• PR base (Step 6): the target branch for the PR. Default to the same default branch unless the repo follows gitflow (presence of a develop branch — check with git rev-parse --verify develop — in which case target develop).

Never hardcode master or develop.

Workflow

Step 1: Gather Git Information

First, detect the diff base (see "Detecting base branches" above). Store it as $BASE.

1. Get current branch name: git branch --show-current
2. Get commit diff summary: git diff $BASE...HEAD --stat
3. Get recent commit messages: git log $BASE..HEAD --oneline
4. Check if changes are pushed: git status -sb

Step 2: Analyze Changes

1. Read the modified files to understand what was changed
2. Identify the type of change (bug fix, feature, refactor, etc.)
3. Extract key changes and their impact
4. Determine affected components

Step 3: Interactive Questions

Use the AskUserQuestion tool to collect information. Ask questions one at a time for better UX.

Question 1: PR Type

Question: "What is the type of change for this PR?"
Options:
- Bug fix - A fix that resolves an issue without breaking existing functionality
- New feature - Functionality that adds a capability to the system
- Breaking change - A change that breaks backward compatibility
- Refactor - Code improvement without changing behavior
- Configuration - Changes to config, properties, Docker, etc.
- Performance - Performance improvement
- Documentation - Documentation-only changes
MultiSelect: false

Question 2: Jira Link Validation

Question: "Is the Jira link correct? https://{{company_name}}.atlassian.net/browse/{BRANCH-NAME}"
Options:
- Yes, it's correct
- No, I'll provide the correct link
MultiSelect: false

If "No", ask follow-up question:

Question: "What is the correct Jira link?"
(Use free text from "Other" option)

Question 3: Additional Links

Question: "Would you like to add related links? (Select all that apply)"
Options:
- Database ticket
- Security ticket
- Technical documentation
- Design/mockup link
- None
MultiSelect: true

For each selected option (except "None"), ask:

Question: "Paste the link for: {link_type}"
(Use free text from "Other" option)

Question 4: Development Checklist

Question: "Check the development checklist items that apply:"
Options:
- Tests run locally (unit, E2E, integration)
- Code reviewed line by line
- Logs are consistent (correct level)
- Sensitive data checked (no exposure)
- External variables created (secrets, feature flags)
- Required tickets executed (database, SQS, security)
MultiSelect: true

Question 5: Impact Sections

Question: "Are there special impacts to document?"
Options:
- Performance - There is a performance impact
- Compatibility - There are breaking changes
- Rollback - Non-standard rollback procedure
- No special impact
MultiSelect: true

For each selected impact, ask for details:

Question: "Describe the {impact_type} impact:"
(Use free text from "Other" option)

Question 6: Reviewer Notes

Question: "Would you like to add attention points for the reviewer?"
Options:
- Yes, I'll add specific points
- No, the PR is self-explanatory
MultiSelect: false

If "Yes", ask:

Question: "Describe the attention points for the reviewer:"
(Use free text from "Other" option)

Step 4: Generate PR Classification

Based on branch name and changes, generate classification in format:

{type}({scope}): {subject}

Examples:

• feat(PROJ-729): add support for store name in payment processing
• fix(PROJ-814): enhance error handling and observability in webhook processing
• refactor(PROJ-901): simplify payment validation logic
• perf(PROJ-732): optimize database queries in order processing

type options:

• feat - New functionality
• fix - Bug fix
• docs - Documentation only
• style - Formatting, lint
• refactor - Refactor without behavior change
• perf - Performance improvement
• test - Adding/fixing tests
• chore - Maintenance, build, CI/CD tasks

Step 5: Generate PR Description

Read assets/pull_request_template.md for the canonical template structure, section format, and a complete filled-out example. The PR body MUST follow this template exactly.

Build the PR body following that template exactly. Fill each section with data collected from Steps 1-4:

• Classification: {type}({scope}): {subject} from Step 4
• Description: Generate from git diff and commit messages. Be concise.
• Links and References: Jira link + any additional links from user answers
• Type of Change: Mark checkboxes based on user selection
• Checklist: Mark checkboxes based on user answers
• Impact and Considerations: Content from user answers, or defaults ("No impact", "100% compatible", "Safe rollback")
• For the Reviewer: Content from user answers or "N/A"

Append at the end:

## Modified Files

{output of git diff --stat}

### Technical Details

{analyze changed files and provide bullet list of key changes with line numbers}

Step 6: Create PR

1. Detect the PR base branch (see "Detecting base branches" above). Store it as $PR_BASE.
2. Verify branch is pushed: Check git status -sb shows tracking info
3. If not pushed, ask user: "Branch is not on remote. Push now?"
4. If yes: git push -u origin {branch-name}
5. Create PR: gh pr create --base $PR_BASE --title "{title}" --body "{body}"
6. Return PR URL to user

Step 7: Post-Creation Summary

Provide clear summary:

✅ PR #{number} created successfully!

**URL:** {pr_url}

**Summary:**
- Type: {type}
- Files modified: {count}
- Checklist completed: {marked_items}/{total_items}

**Next steps:**
1. Review the PR on GitHub
2. Request appropriate reviewers
3. Wait for CI/CD to pass
4. Merge after approval

Important Guidelines

DO:

• Ask questions one at a time using AskUserQuestion tool
• Use multiSelect: true only when multiple selections make sense
• Provide clear, concise option labels in English
• Generate smart defaults based on git history and code analysis
• Include file paths and line numbers in technical details
• Verify branch is pushed before creating PR
• Handle errors gracefully (e.g., branch not found, gh CLI not authenticated)

DON'T:

• Ask all questions at once (overwhelming)
• Use technical jargon in questions — keep it simple
• Skip analysis of changed files
• Create PR without user confirmation
• Include excessive verbosity in descriptions (the template warns against it)

Error Handling

Branch not pushed:

⚠️ Branch {branch-name} is not on remote.
Push now? (git push -u origin {branch-name})

No changes committed:

❌ No commits to create a PR.
Please commit your changes first.

gh CLI not authenticated:

❌ GitHub CLI is not authenticated.
Run: gh auth login

PR already exists:

ℹ️ A PR already exists for this branch: {existing_pr_url}
Would you like to update its description?

Example Usage

User: /creating-pull-request or "Create a PR for this branch"

Skill Flow:

1. Analyzes branch PROJ-814
2. Identifies changes in 2 files (error handling)
3. Asks PR type → User selects "Bug fix"
4. Validates Jira link → User confirms
5. Asks for additional links → User selects "None"
6. Asks checklist → User marks 5/6 items
7. Asks impacts → User selects "No special impact"
8. Asks reviewer notes → User adds notes
9. Generates classification: fix(PROJ-814): enhance error handling
10. Creates PR with full description
11. Returns PR URL #39

Tips for Better PRs

• Be concise: The template warns against excessive verbosity
• Focus on why: Explain motivation, not just what changed
• Add context: Help reviewers understand business impact
• Highlight risks: Call out potential issues proactively
• Test thoroughly: Mark checklist items honestly
• Think about rollback: Always have a plan B