Bitbucket Workflow Skill

This skill handles Bitbucket PR creation and pipeline debugging using Carefeed team conventions. It integrates with Jira for ticket linking and follows team standards for PR formatting.

When to Use This Skill

Automatically trigger this skill when the user:

• Wants to create a PR: "Create a PR", "Open a pull request", "Submit for review"
• Mentions pipeline issues: "Pipeline failed", "CI is broken", "Build failed"
• Asks about PR status: "What's the status of my PR?", "Any comments on the PR?"
• Needs to debug failures: "Why did the build fail?", "What's wrong with the pipeline?"

Part 1: Creating Pull Requests

Prerequisites

• Current branch follows naming: {type}/{JIRA-KEY}-{description}
• Branch has commits ahead of target (usually master)
• All changes are committed

Workflow

Step 1: Verify Branch State

# Check commits ahead of target
git log origin/master..HEAD --oneline | wc -l

# Verify branch name format
git rev-parse --abbrev-ref HEAD

Step 2: Extract Jira Ticket

Parse Jira key from branch name:

• feature/CORE-3982-null-safety-fuzzy-matching -> CORE-3982

Fetch ticket details:

mcp__jira__jira_get_issue(issueIdOrKey: "CORE-3982")

Step 3: Generate PR Description

Carefeed PR Template:

## Jira Ticket
[CORE-3982](https://carefeed.atlassian.net/browse/CORE-3982)

## Summary
[Brief overview from Jira or custom text]

## Changes
* [List of key changes]

## Testing
* [How changes were tested]

## Related
* [Related PRs/issues if applicable]

Generated with [Claude Code](https://claude.com/claude-code)

Step 4: Create PR via MCP

mcp__bitbucket__bb_add_pr({
  repoSlug: "portal_dev",
  prTitle: "CORE-3982: Handle null facility names in fuzzy matching",
  sourceBranch: "feature/CORE-3982-null-safety-fuzzy-matching",
  destinationBranch: "master",
  description: "[Generated description]",
  closeSourceBranch: false
})

Step 5: Link to Jira

Add comment to Jira ticket:

mcp__jira__jira_add_comment(
  issueIdOrKey: "CORE-3982",
  commentBody: "Pull Request created: [PR #4067](pr_url)"
)

Optionally transition to "In Review":

mcp__jira__jira_transition_issue(
  issueIdOrKey: "CORE-3982",
  transitionId: "In Review"
)

PR Title Format

Always include Jira key:

{JIRA-KEY}: {Jira issue summary}

Example: CORE-3982: Handle null facility names in fuzzy matching

Team-Specific Practices

Team	Requirements
Core	Tech lead approval, extra review for DB migrations
Integration	PCC staging test, document env vars
Payments	Security review, test with Stripe test mode

---

Part 2: Debugging Pipeline Failures

Workflow

Step 1: Identify Failed Pipeline

List recent failed pipelines:

mcp__bitbucket__bb_list_pipelines({
  repoSlug: "portal_dev",
  state: "COMPLETED",
  result: "FAILED",
  limit: 10
})

Or get pipeline from PR:

mcp__bitbucket__bb_get_pr({
  repoSlug: "portal_dev",
  prId: "4067"
})

Step 2: Get Pipeline Overview

mcp__bitbucket__bb_get_pipeline({
  repoSlug: "portal_dev",
  pipelineId: "13906"
})

Returns:

• Build number and status
• Branch and commit
• Duration
• Result (SUCCESSFUL, FAILED, ERROR)

Step 3: List Pipeline Steps

mcp__bitbucket__bb_list_pipeline_steps({
  repoSlug: "portal_dev",
  pipelineId: "13906"
})

Step Status Legend:

• SUCCESSFUL - Step passed
• FAILED - Investigate this one
• IN_PROGRESS - Still running
• SKIPPED - Dependency failed

Step 4: Analyze Failure

Note: Bitbucket API doesn't expose step logs programmatically. You must view logs in the browser using the step URL.

Common PHP Test Failures:

• Fatal error: Undefined method
• Failed asserting that null is...
• PDOException: SQLSTATE[23000]

Common Build Failures:

• composer install failed
• npm install failed
• Docker build failed

Common Lint Failures:

• PHPStan: Found X errors
• PHP_CodeSniffer: X violations

Step 5: Correlate with Changes

Find last successful pipeline and compare:

mcp__bitbucket__bb_list_pipelines({
  repoSlug: "portal_dev",
  branch: "feature/CORE-3982",
  result: "SUCCESSFUL",
  limit: 1
})

Then diff the commits:

git diff --name-only [last-success-commit] [failed-commit]

Step 6: Suggest Fix

Match error patterns to common causes:

Error Pattern	Likely Cause
Undefined method X	Missing/renamed method
Failed asserting null	Test expects value but got null
SQLSTATE[23000]	Database constraint violation
composer install failed	Dependency conflict
Class not found	Missing import/autoload

Pipeline Structure

Pipeline (build #13906)
  +-- Step 1: Build (docker, composer, npm)
  +-- Step 2: Test (phpunit, jest)
  +-- Step 3: Lint (phpstan, eslint)
  +-- Step 4: Deploy (if tests pass)

Steps run sequentially by default. If a step fails, subsequent steps are SKIPPED.

---

Example Conversations

Creating a PR

User: "Create a PR for this branch"

Claude:

I'll create a PR for your current branch.

Current branch: feature/CORE-3982-null-safety-fuzzy-matching
Jira ticket: CORE-3982 - Handle null facility names in fuzzy matching
Target: master (1 commit ahead)

PR Title: CORE-3982: Handle null facility names in fuzzy matching

Creating PR...

Created PR #4067: CORE-3982: Handle null facility names in fuzzy matching
https://bitbucket.org/Bitbucketpassword1/portal_dev/pull-requests/4067

Jira ticket CORE-3982 updated with PR link.

Debugging a Pipeline

User: "Pipeline #13906 failed, can you help debug?"

Claude:

I'll investigate pipeline #13906.

Pipeline Overview:
  Build: 13906
  Result: FAILED
  Branch: feature/CORE-3982-null-safety
  Duration: 3m 32s

Pipeline Steps:
  SUCCESSFUL Build
  FAILED PHP Test  <-- This is where it failed
  SKIPPED Deploy

The PHP Test step failed. View logs at:
https://bitbucket.org/.../steps/{uuid}

Recent changes in this branch:
  - app/Services/MarketAnalytics/FacilityMatcher.php
  - tests/Unit/MarketAnalytics/FacilityMatcherTest.php

Likely cause: Test expects non-null value but code now returns null for edge case.

Would you like me to:
1. Show the specific changes to FacilityMatcher.php
2. Help fix the test
3. Run tests locally first

---

Error Handling

Branch doesn't contain Jira key

Ask user for the Jira ticket or suggest renaming the branch.

No commits ahead of target

User needs to make changes and commit first.

Bitbucket authentication failed

Check MCP server is running and credentials are configured.

Pipeline not found

List recent pipelines to find the correct ID.

Logs not accessible via API

Provide the step URL for browser access (API limitation).

---

Anti-Patterns

• Don't create PRs without checking for existing open PRs on the branch
• Don't skip Jira ticket extraction - always link PRs to tickets
• Don't guess at failure causes without checking the changed files
• Don't assume logs are available via API - they require browser access