vivekcse86/viv-commit-and-pr

Use When

Invoke this skill when the user wants to:

• Create a pull request following standard workflow.
• Ensure uncommitted work is committed with the correct JIRA issue reference(s) before opening a PR.
• Generate a well-formatted PR title and description automatically from the diff.
• Standardize commit messages across the team by enforcing the [JIRA-XXXX] prefix convention.

Supports two modes. See Invocation Modes below.

Do not invoke this skill for:

• General git operations (branching, rebasing, merging) unrelated to PR creation.
• Questions about git or GitHub without intent to open a PR.

---

Invocation Modes

Detect the mode from the user's invocation message before running any steps.

| Keywords in message | Mode | Behaviour | |---|---|---| | (none) / create PR / standard invocation | Streamlined (default) | Auto-creates PR immediately — no draft review stop. | | detailed / full / review / with review | Review | Shows generated title + body, waits for approval/edits, then creates. |

Store as {MODE} = streamlined or review.

Examples:

• /viv-commit-and-pr -> streamlined
• create PR detailed -> review
• make a PR full -> review
• push and create PR with review -> review

---

Workflow

Execute these steps in order. Do not skip steps or proceed past a step that requires user input without receiving it.

---

Step 1 — Auto-Detect and Confirm Setup

Performs all detection silently and presents a single prompt to the user — combining JIRA key detection and target branch selection.

1a. Detect invocation mode

Inspect the user's message for the keywords detailed, full, review, or with review.

• If found -> {MODE} = review
• Otherwise -> {MODE} = streamlined

1b. Verify git repository

Run:

git rev-parse --is-inside-work-tree

• If this fails -> inform the user: "This folder does not appear to be a git repository. Please open a workspace folder that is inside a git repository." and stop.
• If it succeeds -> continue.

1c. Detect JIRA key(s) from branch name

Run:

git branch --show-current

Store the result as {BRANCH_NAME}.

Scan {BRANCH_NAME} for substrings matching the pattern [A-Z]+-\d+.

Common patterns to recognise:

• feature/MBL-1327-description -> MBL-1327
• MBL-1327/some-feature -> MBL-1327
• bugfix/vivIT-99-fix-thing -> vivIT-99
• feature/vivIT-2345 -> vivIT-2345

1d. Show one consolidated prompt

If one or more JIRA key(s) were found, present:

"I found {EXTRACTED_KEY(S)} from branch {BRANCH_NAME}. Target: main (default). Reply go to proceed, or customize: — Different JIRA: POS-1123 — Multiple JIRA: MBL-1327, POS-1123 — Different target: MBL-1327 > develop or MBL-1327 to develop — Both: MBL-1327, POS-1123 > develop"

If no JIRA key was found (or git branch --show-current returned empty):

"What JIRA issue(s) and target branch? Examples: MBL-1327 · MBL-1327, POS-1123 · MBL-1327 > develop · MBL-1327, POS-1123 > develop (Target defaults to main if not specified)"

1e. Parse and validate the response

1. If the reply is go or any affirmative with no overrides -> keep the extracted JIRA key(s) and set {TARGET_BRANCH} = main.
2. Otherwise extract:
   • JIRA keys: everything before the > or to separator — split on commas, trim whitespace, validate each against [A-Z]+-\d+.
   • Target branch: the value after > or to, trimmed. Default to main if absent.

Store the validated, comma-separated JIRA key string as {JIRA_ISSUES} (e.g. MBL-1327, POS-1123). Store the target branch as {TARGET_BRANCH}.

If any JIRA key fails validation, explain the expected format (PROJ-1234) and ask the user to correct only the invalid entries.

Verify the target branch exists on the remote:

git ls-remote --heads origin {TARGET_BRANCH}

If not found: "Branch {TARGET_BRANCH} was not found on the remote. Please confirm the target branch name." and re-ask for just the target.

---

Step 2 — Check for Uncommitted Changes

Run:

git status --short

• If the output is empty -> inform the user: "No uncommitted changes detected — skipping commit step." Continue to Step 4.
• If the output is non-empty -> proceed to Step 3.

---

Step 3 — Commit Uncommitted Changes

3a. Show the pending change list

Parse the git status --short output from Step 2 and present it to the user grouped by status, using plain labels. Use the two-character git status codes to assign each file to a group:

• M, MM -> Modified
• A, AM -> Added (staged)
• D -> Deleted
• R -> Renamed
• ?? -> New / untracked (not yet staged — will be included unless excluded)

Present the list like this:

Here's what will be committed:

Modified

• src/OrderService.cs
• src/CustomerService.cs

New / untracked

• scratch.txt
• src/NewFeature.cs

Reply go to commit all, or exclude files with: exclude scratch.txt or exclude scratch.txt, temp/

If there are no untracked (??) files, skip the prompt entirely — proceed directly to Step 3b without waiting for a reply.

3b. Parse exclusions (if any)

• If the user replied go or any affirmative -> {EXCLUDED_FILES} = (empty).
• If the user listed exclusions -> parse the comma-separated file/folder names as {EXCLUDED_FILES}.

3c. Stage all changes except exclusions

If {EXCLUDED_FILES} is empty, run:

git add --all

If {EXCLUDED_FILES} is non-empty, stage everything individually except the excluded paths:

git add --all
git restore --staged {EXCLUDED_FILES}

This keeps the excluded files in the working tree — they remain as untracked or unstaged local files and are not removed.

3d. Summarize the staged changes

Run:

git diff --cached

Read the full staged diff — which now accurately reflects exactly what will be committed, including any new files — and compose a concise, imperative-mood summary. Keep it under 72 characters. Examples:

• Add order validation logic and update DTO mappings
• Fix null reference in CustomerService and add unit tests
• Refactor PaymentProcessor to use strategy pattern

Store this as {COMMIT_SUMMARY}.

3e. Commit with JIRA issue key prefix

Run:

git commit -m "[{JIRA_ISSUES}] {COMMIT_SUMMARY}"

Confirm to the user:

"Committed: [{JIRA_ISSUES}] {COMMIT_SUMMARY}"

If the commit fails, show the error output and stop — do not push or create a PR until the commit succeeds.

---

Step 4 — Identify Current Branch

Run:

git branch --show-current

Store the result as {CURRENT_BRANCH}.

If the result is empty (detached HEAD state), inform the user: "You are in a detached HEAD state. Please check out a named branch before creating a PR." and stop.

---

Step 5 — Push the Current Branch

Run:

git push --set-upstream origin {CURRENT_BRANCH}

If this fails because the upstream is already set, run:

git push

• If push fails with an authentication error -> instruct the user to run gh auth login or configure their git credentials, then retry.
• If push fails because the branch is protected -> inform the user and suggest creating a new feature branch to carry the changes.
• If push succeeds -> confirm: "Branch {CURRENT_BRANCH} pushed to origin."

---

Step 6 — Generate PR Title and Body

6a. Gather commit log

Run:

git log origin/{TARGET_BRANCH}..{CURRENT_BRANCH} --oneline

If there are no commits between the branches, inform the user: "No commits found between {TARGET_BRANCH} and {CURRENT_BRANCH} — branches appear to be identical. Nothing to PR." and stop.

6b. Gather change statistics

Run:

git diff origin/{TARGET_BRANCH}...{CURRENT_BRANCH} --stat

6c. Compose PR title

The entire title — including the [{JIRA_ISSUES}] prefix — MUST be ≤ 72 characters total.

Format: [{JIRA_ISSUES}] <imperative-mood summary>

When multiple JIRA keys make the prefix longer, shorten the summary accordingly. Character budget: 72 − length of [{JIRA_ISSUES}] = remaining characters for the summary.

Example (single key): [FNLIT-1234] Add customer address validation and update checkout flow Example (multi-key): [MBL-1327, POS-1123] Add address validation and fix mobile checkout

6d. Compose PR body

Use the following fixed Markdown template, filling in each section from the commit log and diff stat:

## Summary

<2–4 sentences describing what this PR does, the problem it solves, and any important design decisions. Derived from the commit log and diff.>

## Changes

- <Bullet per logical change group, derived from the commit log and diff stat>

## JIRA

<One bullet per key in {JIRA_ISSUES}. If a JIRA base URL is configured in the agent environment table, render as a Markdown link; otherwise render the key as plain text.>

**If JIRA base URL is configured** (e.g. `https://vivek.atlassian.net/browse/`):
- [MBL-1327](https://vivek.atlassian.net/browse/MBL-1327)
- [POS-1123](https://vivek.atlassian.net/browse/POS-1123)

**If JIRA base URL is not configured:**
- MBL-1327
- POS-1123

6e. Review gate — conditional on {MODE}

Streamlined mode ({MODE} = streamlined): Skip this gate. Proceed directly to Step 7.

Review mode ({MODE} = review): Present the generated title and body and ask:

"Does this PR description look good? Reply yes to create it, or tell me what to change."

• If the user says yes or any affirmative -> proceed to Step 7.
• If the user requests edits -> apply the edits, show the updated draft, and ask again. Repeat until approved.

---

Step 7 — Create the Pull Request

Use the GitHub pull request tool to create a PR with:

• title: the PR title from Step 6c
• body: the PR body from Step 6d
• head branch: {CURRENT_BRANCH}
• base branch: {TARGET_BRANCH}

On success, report the PR URL to the user:

"Pull request created: <PR_URL>"

If the PR creation tool fails, show the error and suggest opening the PR manually via the GitHub web UI.

---

Error Handling Reference

| Situation | Response | |-----------|----------| | Not a git repository | Inform user and stop (Step 1b). | | Invalid JIRA key format | Explain PROJ-1234 format and re-ask for only the invalid keys (Step 1e). | | Target branch not found on remote | Ask user to confirm the branch name (Step 1e). | | Commit fails | Show error, do not continue to push/PR. | | Excluded files left unstaged | Files remain as untracked/modified local files — not lost. | | Detached HEAD | Ask user to check out a named branch before proceeding. | | Push — auth failure | Guide user to authenticate (gh auth login). | | Push — protected branch | Suggest creating a feature branch. | | No commits between branches | Inform user branches are identical — nothing to PR. | | PR creation tool fails | Show the error; suggest opening the PR manually via the GitHub web UI. |

---

Conventions

• Commit message format: [JIRA-XXXX] Imperative mood summary under 72 chars
• Multi-JIRA format: [MBL-1327, POS-1123] Imperative mood summary under 72 chars
• PR title format: matches commit message format
• JIRA link base URL: read from the agent environment table (JIRA base URL row); if not configured, list JIRA keys as plain text — do not fabricate a URL
• Default target branch: main
• Target branch separator: > or the word to (e.g. MBL-1327 > develop or MBL-1327 to develop)
• Default mode: streamlined — PR auto-created with no draft review stop
• Review mode trigger: include detailed, full, review, or with review in the invocation message