Pr

CRITICAL: This skill is fully autonomous and MUST NOT use AskUserQuestion or request any user input.

Key behaviors:

• Auto-detect issue references from branch name and commits
• Autonomously infer PR type and scope from changes
• Generate PR title in conventional commit format
• Create human-readable summary, changes, and test plan sections
• Include collapsible agent context with file list and intent
• Execute gh pr create directly without confirmation

This skill is designed for non-interactive execution with claude -p. It MUST:

• NEVER use AskUserQuestion tool
• NEVER prompt the user for confirmation
• NEVER show a preview and wait for approval
• ALWAYS make autonomous decisions about type, scope, and content
• ALWAYS proceed directly to PR creation after gathering context

If pre-flight checks fail (no commits, branch not pushed, PR exists), report the issue and exit gracefully - do not prompt for user action.

At the END of your response, output a YAML block with the PR creation result. The mobius loop parses this to execute issue linking via SDK.

Output format (YAML):

---
status: PR_CREATED  # or PR_EXISTS, PR_FAILED, NO_CHANGES
timestamp: "2026-01-28T12:00:00Z"  # ISO-8601 timestamp

# For PR_CREATED:
prUrl: "https://github.com/owner/repo/pull/123"
prNumber: 123
prTitle: "feat(scope): description"
prBase: "main"
prHead: "feature-branch"
isDraft: false

# Issue linking data (for mobius loop to process):
linkedIssues:
  - identifier: "MOB-72"
    validated: true  # true if validated from local context
    title: "Issue title if known"
backend: linear  # or jira

# For PR_EXISTS:
existingPrUrl: "https://github.com/owner/repo/pull/100"
existingPrNumber: 100

# For PR_FAILED:
errorType: "no_commits"  # no_commits | not_pushed | auth_failed | gh_error
errorMessage: "No commits between main and current branch"

# For NO_CHANGES:
# (no additional fields needed)
---

Valid status values:

Critical requirements:

1. Output MUST be valid YAML
2. Output MUST appear at the END of your response
3. Output MUST include status and timestamp fields
4. Include linkedIssues array for all detected issue IDs (even unvalidated ones)

Example complete output for successful PR:

---
status: PR_CREATED
timestamp: "2026-01-28T16:45:00Z"
prUrl: "https://github.com/verz/mobius/pull/456"
prNumber: 456
prTitle: "feat(skills): add PR creation skill"
prBase: "main"
prHead: "drverzal/mob-72-add-pr-skill"
isDraft: false
linkedIssues:
  - identifier: "MOB-72"
    validated: true
    title: "Add PR skill for structured pull request creation"
backend: linear
---

Example output when PR already exists:

---
status: PR_EXISTS
timestamp: "2026-01-28T16:45:00Z"
existingPrUrl: "https://github.com/verz/mobius/pull/400"
existingPrNumber: 400
linkedIssues:
  - identifier: "MOB-72"
    validated: false
backend: linear
---

Read ~/.config/mobius/config.yaml or mobius.config.yaml in the project root:

backend: linear  # or 'jira'

Default: If no backend is specified, default to linear.

The detected backend determines the issue ID format and linking output. See <backend_context> for details per backend.

When backend detection is needed:

• Issue references are detected from branch name or commits
• User wants to link PR back to issue tracker
• Generating structured output for issue linking

When backend detection can be skipped:

• No issue references found
• User explicitly opts out of issue linking

Issue ID formats:

• MOB-123, PROJ-456, ABC-789 (uppercase prefix + number)
• Regex: /^[A-Z]{2,10}-\d+$/

Validation via local context (optional): If the MOBIUS_CONTEXT_FILE environment variable is set or local context exists at ~/.mobius/issues/{parentId}/, read issue details from local files instead of making API calls.

# Check if context file exists
if [ -n "$MOBIUS_CONTEXT_FILE" ] && [ -f "$MOBIUS_CONTEXT_FILE" ]; then
  # Read issue details from local context
  cat "$MOBIUS_CONTEXT_FILE" | jq '.parent'
fi

Linking output: PR-issue linking is handled via structured output (see <structured_output> section).

Issue ID formats:

• PROJ-123, JIRA-456, KEY-789 (uppercase prefix + number)
• Regex: /^[A-Z]{2,10}-\d+$/

Validation via local context (optional): If the MOBIUS_CONTEXT_FILE environment variable is set or local context exists at ~/.mobius/issues/{parentId}/, read issue details from local files instead of making API calls.

# Check if context file exists
if [ -n "$MOBIUS_CONTEXT_FILE" ] && [ -f "$MOBIUS_CONTEXT_FILE" ]; then
  # Read issue details from local context
  cat "$MOBIUS_CONTEXT_FILE" | jq '.parent'
fi

Linking output: PR-issue linking is handled via structured output (see <structured_output> section).

Do NOT attempt to link when:

• No issue references detected
• Issue validation fails (invalid ID)

Option 1: Local context validation (preferred)

If MOBIUS_CONTEXT_FILE is set or local context exists:

# Read from local context
if [ -n "$MOBIUS_CONTEXT_FILE" ] && [ -f "$MOBIUS_CONTEXT_FILE" ]; then
  ISSUE_TITLE=$(cat "$MOBIUS_CONTEXT_FILE" | jq -r '.parent.title')
  ISSUE_ID=$(cat "$MOBIUS_CONTEXT_FILE" | jq -r '.parent.identifier')
  echo "Validated: $ISSUE_ID - $ISSUE_TITLE"
fi

Option 2: No validation available

If no local context exists:

• Warn user: "Could not validate issue MOB-123 - no local context available"
• Continue with PR creation (do NOT block)
• Include issue reference in PR body anyway (GitHub/Linear may auto-link)

Important: This skill does NOT call MCP tools directly. Issue linking is deferred to structured output for the mobius loop to handle.

The mobius loop will parse the structured output and execute the linking via SDK. This skill does NOT directly call issue tracker APIs.

See <structured_output> section for the output format that enables linking.

Since this skill outputs structured data for the mobius loop to process, linking errors are handled by the loop, not this skill.

If no local context is available for validation:

• Warn in output: "Issue validation skipped (no local context)"
• Include detected issue IDs in structured output anyway
• The loop will attempt linking and report any errors

Example warning output:

## PR Created Successfully
URL: https://github.com/owner/repo/pull/456

ℹ️ **Issue Linking Deferred**
Detected issues: MOB-123
Linking will be handled by the mobius loop via structured output.

If running standalone, manually link:
1. Open https://linear.app/team/issue/MOB-123
2. Add link: https://github.com/owner/repo/pull/456

# Current branch
git branch --show-current

# Default base branch (usually main or master)
git remote show origin | grep 'HEAD branch' | cut -d: -f2 | xargs

# Or use configured base
git config --get init.defaultBranch || echo "main"

Branch name patterns for issue detection:

• drverzal/mob-123-feature-description -> MOB-123
• feature/PROJ-456-add-login -> PROJ-456
• fix/123-bug-description -> #123 (GitHub issue)
• bugfix/jira-789 -> JIRA-789

Regex patterns to extract issue IDs:

# Linear/Jira style: MOB-123, PROJ-456, ABC-789 (case-insensitive)
/([A-Z]{2,10}-\d+)/gi

# GitHub issue style: #123 or refs/123
/#?(\d+)/g

Note: Branch names often contain lowercase issue IDs (e.g., mob-72 instead of MOB-72). Always use case-insensitive matching and normalize to uppercase for display.

From commit messages (secondary source):

# Get commits on this branch not in base
git log origin/main..HEAD --pretty=format:"%s%n%b"

Look for patterns:

• Refs: MOB-123
• Closes #456
• Implements: PROJ-789
• Part-of: MOB-100

Diff statistics

git diff --stat origin/main...HEAD

Detailed diff for context

git diff origin/main...HEAD

**Commit history on branch**:
```bash
# Commits since branching from base
git log --oneline origin/main..HEAD

Detection priority:

1. Explicit type in branch name: fix/mob-123 -> fix
2. Commit message prefixes: feat: add login -> feat
3. File pattern analysis (fallback)

If uncertain, default to feat for new features or fix for bug-related work.

If changes span multiple areas, use the primary area or omit scope.

<type>(<scope>): <description>

Rules:

• Use imperative mood: "add" not "added"
• Keep under 72 characters
• No issue numbers in title (put in body)
• Scope is optional but helpful

Examples:

• feat(auth): add OAuth2 login with Google provider
• fix(cart): prevent duplicate items on double-click
• refactor(api): extract authentication middleware
• docs(readme): update installation instructions

Changes

• [Bullet point describing change 1]
• [Bullet point describing change 2]
• [Bullet point describing change 3]

Test Plan

• [How to verify change 1]
• [How to verify change 2]

Refs: {ISSUE-ID}

Files Changed

• path/to/file1.ts - [brief description of change]
• path/to/file2.ts - [brief description of change]

Intent

[Why this change was made - connects to issue context and broader goals]

Dependencies

• Provides: [What this PR exports/enables for other code]
• Consumes: [What this PR depends on]
• Affects: [What existing functionality this might impact]

Changes (bullet points):

• One bullet per logical change
• Start with verb: "Add", "Update", "Remove", "Fix"
• Be specific but concise
• Group by area if many changes

Test Plan (checkboxes):

• Include automated test commands
• Add manual verification steps
• Cover edge cases if applicable

Refs (issue references):

• Use Refs: for Linear/Jira issues
• Use Closes: or Fixes: for GitHub issues (auto-closes)
• Multiple refs: Refs: MOB-123, MOB-124

Agent Context (collapsible):

• Always in <details> tag to keep main view clean
• Files Changed: Explicit paths with descriptions
• Intent: The "why" for AI reviewers
• Dependencies: Impact analysis for automated tools

GitHub issue style:

/\b#(\d+)\b/g

Matches: #123, #456

In commit trailers:

/^(Refs|Closes|Fixes|Implements|Part-of):\s*(.+)$/gm

Matches: Refs: MOB-123, Closes: #456

Extraction logic:

1. Split branch name by /
2. Search each segment for issue patterns
3. Return first match (usually in second segment)

# Get all commit messages on branch (case-insensitive, normalize to uppercase)
git log origin/main..HEAD --pretty=format:"%B" | grep -oiE "[A-Z]{2,10}-[0-9]+" | tr '[:lower:]' '[:upper:]' | sort -u

Deduplicate and combine with branch-detected issues.

Get base branch

BASE=$(git config --get pr.base || echo "main")

Check if remote branch exists

git ls-remote --exit-code --heads origin "$BRANCH" 2>/dev/null

Get changed files

git diff --name-only origin/$BASE...HEAD

Get commit log

git log --oneline origin/$BASE..HEAD

</step_1_gather_context>

<step_2_detect_issues>
Parse branch name and commits for issue references using patterns from `<issue_detection>`.

Build reference string:
- Primary issue from branch: `Refs: MOB-123`
- Additional issues from commits: `Refs: MOB-123, MOB-124`
</step_2_detect_issues>

<step_2b_validate_issues>
If issue references were detected, attempt to validate them before proceeding.

**Validation via local context (preferred)**:

1. Check if `MOBIUS_CONTEXT_FILE` environment variable is set
2. If set, read issue details from local context file
3. Extract issue title and status for enhanced PR context

```bash
# Check for local context
if [ -n "$MOBIUS_CONTEXT_FILE" ] && [ -f "$MOBIUS_CONTEXT_FILE" ]; then
  ISSUE_ID=$(cat "$MOBIUS_CONTEXT_FILE" | jq -r '.parent.identifier')
  ISSUE_TITLE=$(cat "$MOBIUS_CONTEXT_FILE" | jq -r '.parent.title')
  echo "Validated from context: $ISSUE_ID - $ISSUE_TITLE"
fi

If no local context available:

• Warn: "Could not validate issue MOB-123 - no local context"
• Continue with PR creation (do NOT block)
• Include issue ID in Refs: section anyway

Example validation output:

Detected issues:
- MOB-72: "Add PR skill for structured pull request creation" ✓ (from context)
- MOB-123: Could not validate (no local context) ⚠️

Store validated issues for use in:

• PR body Refs: section (all detected references)
• Structured output for post-creation linking

Autonomous type inference priority (DO NOT ask user):

1. Explicit type in branch name: fix/mob-123 -> fix
2. Commit message prefixes: feat: add login -> feat
3. File pattern analysis:
   • New files in src/ -> feat
   • Test files only -> test
   • Docs files only -> docs
   • Config/build changes -> build or ci
4. Default fallback: If still ambiguous, use feat for new code or fix for modifications

Never ask user for type clarification - make the best autonomous decision.

1. Title: {type}({scope}): {description} - infer from branch/commits
2. Summary: Generate 1-2 sentences from commit messages and diff analysis
3. Changes: Bullet points derived from file changes and commit messages
4. Test Plan: Generate from test files changed, include npm test or equivalent
5. Refs: Issue references detected from branch/commits
6. Agent Context: File list with descriptions, intent from commits, dependency analysis

Do NOT ask user for any content - generate everything autonomously.

Proceed directly to gh pr create with the generated content.

This skill is autonomous - do not show preview, do not ask for confirmation, do not use AskUserQuestion. Create the PR directly.

gh pr create \
  --title "feat(skills): add PR creation skill" \
  --base main \
  --body "$(cat <<'EOF'
## Summary
...

## Changes
...

## Test Plan
...

Refs: MOB-72

---

<details>
<summary>Agent Context</summary>
...
</details>
EOF
)"

For draft PRs:

gh pr create --draft ...

This skill does NOT directly call issue tracker APIs. Instead, it outputs structured data that the mobius loop parses and executes via SDK.

See <structured_output> section for the complete output format.

The structured output includes:

• prUrl: The URL of the created PR
• prNumber: The PR number
• prTitle: The PR title (conventional commit format)
• linkedIssues: Array of issue IDs to link
• backend: The detected backend (linear/jira)

Example output (included at end of response):

---
status: PR_CREATED
timestamp: "2026-01-28T12:00:00Z"
prUrl: "https://github.com/owner/repo/pull/123"
prNumber: 123
prTitle: "feat(skills): add PR creation skill"
linkedIssues:
  - "MOB-72"
backend: linear
---

The mobius loop will:

1. Parse this structured output
2. Add PR as link attachment to each issue via SDK
3. Add comment documenting PR creation via SDK
4. Report success/failure back to user

If running standalone (not via mobius loop):

• Linking will not occur automatically
• Provide manual linking instructions in the report

## PR Created

**URL**: https://github.com/owner/repo/pull/123
**Title**: feat(skills): add PR creation skill
**Base**: main <- feature-branch
**Status**: Open (or Draft)

### Issue Links
- MOB-72: Linked ✓ ([view in Linear](https://linear.app/team/issue/MOB-72))

### Next Steps
- Request reviewers if needed: `gh pr edit 123 --add-reviewer @username`
- Add labels: `gh pr edit 123 --add-label "enhancement"`
- Mark ready (if draft): `gh pr ready 123`

If issue linking failed, include in report:

### Issue Links
- MOB-72: ⚠️ Link failed - [manual link instructions]

All decisions are made autonomously:

• Type: Inferred from branch name, commits, and file patterns
• Scope: Inferred from changed file paths
• Summary: Generated from commit messages and diff analysis
• Test plan: Generated from test files and standard commands
• Confirmation: NOT REQUIRED - create PR directly

If any information is ambiguous, make the best autonomous decision and proceed. Do not block on missing information - use sensible defaults.

Branch: drverzal/mob-45-add-oauth-login Commits:

• feat(auth): add OAuth2 provider configuration
• feat(auth): implement Google login flow
• test(auth): add OAuth integration tests

Generated PR:

Title: feat(auth): add OAuth2 login with Google provider

## Summary
Add OAuth2 authentication support enabling users to sign in with their Google accounts, reducing friction in the login flow.

## Changes
- Add OAuth2 provider configuration in `src/config/auth.ts`
- Implement Google login flow with token handling
- Add callback route for OAuth redirect
- Create login button component with provider selection
- Add integration tests for OAuth flow

## Test Plan
- [ ] Run `npm test` - all tests pass
- [ ] Manual: Click "Sign in with Google" on login page
- [ ] Manual: Complete OAuth flow, verify redirect to dashboard
- [ ] Manual: Verify user profile shows Google account info

Refs: MOB-45

---

<details>
<summary>Agent Context</summary>

### Files Changed
- `src/config/auth.ts` - OAuth provider configuration
- `src/routes/auth/callback.ts` - OAuth callback handler
- `src/components/LoginButton.tsx` - Updated with provider selection
- `src/services/oauth.ts` - New OAuth service
- `tests/auth/oauth.test.ts` - Integration tests

### Intent
Implements OAuth2 authentication as part of the enterprise SSO initiative (MOB-45).
This enables single sign-on for organizations using Google Workspace.

### Dependencies
- **Provides**: OAuth login capability, GoogleAuthProvider
- **Consumes**: Existing auth context, session management
- **Affects**: Login page, user profile display

</details>

Branch: fix/mob-89-cart-duplicate-items Commits:

• fix(cart): add debounce to prevent duplicate additions

Generated PR:

Title: fix(cart): prevent duplicate items on rapid add-to-cart clicks

## Summary
Fix race condition that caused duplicate cart items when users rapidly clicked the "Add to Cart" button.

## Changes
- Add 300ms debounce to `addToCart` action
- Implement optimistic locking on cart item creation
- Add visual feedback during add operation

## Test Plan
- [ ] Run `npm test` - all tests pass
- [ ] Manual: Rapidly click "Add to Cart" button 5+ times
- [ ] Verify only one item is added to cart
- [ ] Verify button shows loading state during operation

Fixes: #89
Refs: MOB-89

---

<details>
<summary>Agent Context</summary>

### Files Changed
- `src/store/cartSlice.ts` - Added debounce and optimistic locking
- `src/components/AddToCartButton.tsx` - Added loading state

### Intent
Root cause was missing debounce on the add-to-cart action. Multiple rapid clicks
queued multiple API calls before the first completed, resulting in duplicates.

### Dependencies
- **Provides**: Thread-safe cart operations
- **Consumes**: Cart API, debounce utility
- **Affects**: All "Add to Cart" interactions site-wide

</details>

Draft is indicated by:

• /pr --draft argument passed to skill

Mark ready when complete

gh pr ready {pr-number}

</draft_commands>
</draft_pr_handling>

<error_handling>
<common_errors>
**No commits on branch**:

Error: No commits between main and current branch

Solution: Ensure there are committed changes before creating PR.

**Branch not pushed**:

Error: Remote branch not found

Solution: Push branch first with `git push -u origin {branch}`.

**PR already exists**:

Error: A pull request already exists for this branch

Solution: Show existing PR URL, offer to update it.

**Authentication failure**:

Error: gh auth required

Solution: Run `gh auth login` to authenticate.
</common_errors>

<pre_flight_checks>
Before attempting PR creation:

1. **Check for commits**: `git log origin/main..HEAD --oneline`
2. **Check branch is pushed**: `git ls-remote --heads origin {branch}`
3. **Check no existing PR**: `gh pr list --head {branch}`
4. **Check gh auth**: `gh auth status`

If any check fails, report the issue and provide the fix command.
</pre_flight_checks>
</error_handling>

<edge_cases>
<no_issue_detected>
**Branch without issue ID**:

When no issue reference is found in branch name or commits:
1. Proceed with PR creation without issue linking
2. Inform user: "No issue references detected. PR will be created without issue linking."
3. Do NOT block PR creation or prompt user to enter an issue ID
4. `Refs:` line will be omitted from PR body
</no_issue_detected>

<multiple_issues>
**Multiple issue IDs found**:

When multiple issue references are detected:
1. Collect all unique issue IDs from branch name and commits
2. Validate each issue via backend MCP tools
3. Include all validated issues in `Refs:` line: `Refs: MOB-72, MOB-74, MOB-75`
4. Link PR to all validated issues after creation
5. Add comment to each linked issue
</multiple_issues>

<no_changes>
**No changes to commit**:

Detected when `git diff --name-only origin/main...HEAD` returns empty:
1. Report: "No changes detected between current branch and main."
2. Suggest: "Ensure you have committed your changes before creating a PR."
3. Do NOT attempt to create an empty PR
</no_changes>

<pr_already_exists>
**PR already exists for branch**:

Detected by `gh pr list --head {branch}`:
1. Report: "A pull request already exists for this branch."
2. Show existing PR URL and title
3. Exit gracefully - do NOT create a duplicate PR
4. Suggest next steps in output (view with `gh pr view`, edit with `gh pr edit`)
</pr_already_exists>

<lowercase_issue_ids>
**Lowercase issue IDs in branch names**:

Branch names often use lowercase (e.g., `drverzal/mob-72-feature`):
1. Use case-insensitive regex matching: `grep -oiE "[A-Z]{2,10}-[0-9]+"`
2. Normalize extracted IDs to uppercase for display and API calls
3. Example: `mob-72` -> `MOB-72`
</lowercase_issue_ids>
</edge_cases>

<anti_patterns>
**Don't put issue numbers in title**:
- BAD: `feat(auth): add OAuth login (MOB-45)`
- GOOD: `feat(auth): add OAuth login` with `Refs: MOB-45` in body

**Don't use vague titles**:
- BAD: `Update code`
- GOOD: `refactor(api): extract shared validation middleware`

**Don't skip the test plan**:
- BAD: "No tests needed"
- GOOD: Always include at least basic verification steps

**Don't write prose in Changes**:
- BAD: "This PR adds a new feature that allows users to..."
- GOOD: Bullet points starting with verbs

**Don't forget agent context**:
- BAD: Human section only
- GOOD: Include collapsible agent context with file list and intent

**Don't ask for user input** (this is an autonomous skill):
- BAD: Use AskUserQuestion for type/scope/confirmation
- GOOD: Infer everything autonomously and create PR directly

**Don't ignore existing PRs**:
- BAD: Create duplicate PR for same branch
- GOOD: Detect existing PR, offer to update or view it
</anti_patterns>

<success_criteria>
A successful autonomous PR creation achieves:

**Pre-flight checks**:
- [ ] Branch has commits relative to base (or graceful exit if none)
- [ ] Branch is pushed to remote (or auto-push with `git push -u origin`)
- [ ] No existing PR for this branch (or report existing PR URL)
- [ ] GitHub CLI authenticated (`gh auth status`)

**Issue detection**:
- [ ] Issue references detected from branch/commits (case-insensitive)
- [ ] Lowercase issue IDs normalized to uppercase
- [ ] Multiple issues handled correctly (deduplicated)
- [ ] Issues validated from local context file (if MOBIUS_CONTEXT_FILE set)
- [ ] Graceful handling when no issues detected (PR created without linking)

**PR content** (all generated autonomously):
- [ ] PR title follows conventional commit format
- [ ] Type autonomously inferred from changes
- [ ] Summary generated from commits and diff analysis
- [ ] Changes section has clear bullet points
- [ ] Test plan generated from test files and standard commands
- [ ] Issue references included with `Refs:` or `Closes:` (if detected)
- [ ] Agent context section is collapsible
- [ ] Files changed list has paths and descriptions

**Execution** (fully autonomous):
- [ ] NO user confirmation requested
- [ ] PR created directly with `gh pr create`
- [ ] Structured output includes issue linking data
- [ ] PR URL and detected issues reported to user
- [ ] YAML status block output at end of response
</success_criteria>

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/tubular-health) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->