arh-pr-workflow Skill

Expert guidance for arh CLI — Uber's PR and feature branch management tool.

Create Claude task list using TaskCreate for all items below. Mark tasks complete via TaskUpdate as you go.

• Parse user request (which arh operation?)
• Detect environment (Uber production repo?)
• Execute requested operation
• Verify result
• Report outcome

Branch Naming & Commit Templates

See references/uber-commit-template.md for branch naming convention, commit template format, and PR metadata gathering.

Initial Setup

arh auth

Opens browser for GitHub authorization. Select all needed orgs (e.g., uber-code, uber-objectconfig). GitHub username must end with _UBER suffix.

Core Capabilities

1. Creating Feature Branches

Create a new feature branch from main:

arh feature \x3Cfeature-name>

Create a stacked feature (branch off current feature):

arh feature next \x3Cfeature-name>

Create feature with specific parent:

arh feature \x3Cfeature-name> --parent \x3Cparent-branch>

2. Publishing Pull Requests

Publish PR for current feature:

arh publish

Publish entire feature stack (root to leaf):

arh publish --full-stack

Publish without interactive prompts (auto-apply lint fixes):

arh publish --no-interactive

Publish as draft PR:

arh publish --changes-planned

Publish with auto-merge enabled:

arh publish --auto-merge

Publish with combined flags:

arh publish --no-interactive --apply-fixes
arh publish --full-stack --changes-planned

3. Viewing PR Status

View feature tree:

arh log -p

View feature tree with PR status:

arh log -s
# or
arh -s

View with commit history (ahead/behind status):

arh log -c
# or
arh -c

4. Merging Pull Requests

Merge current feature and all ancestors:

arh merge

How it works:

• If on branch A (main -> C -> B -> A), merges A, B, and C
• If on branch B, merges B and C
• Requires all checks to pass (Builds, Required Approvers)
• Merges ancestors first, then current branch

5. Navigating Features

Checkout existing feature:

arh checkout \x3Cfeature-name>
# or
arh co \x3Cfeature-name>

Checkout PR from URL (v0.0.38+):

arh checkout https://github.com/uber-code/go-code/pull/11960
# or
arh checkout uber-code/go-code/pull/11960
# or
arh checkout 11960
# or
arh checkout username/feature-name

This fetches the PR branch from remote and sets up upstream tracking.

Navigate feature stack:

arh checkout next    # Next feature in tree
arh checkout prev    # Previous feature in tree
arh checkout first   # First feature in tree
arh checkout last    # Last feature in tree

6. Rebasing Features

Rebase current feature tree to latest parent:

arh rebase

Pull and rebase from default branch:

arh pull -r

This pulls latest changes from origin main and rebases the entire feature stack.

Important for go-code monorepo: After any git pull or arh pull, always run:

git-bzl refresh

Rebase to new parent:

arh rebase --parent \x3Cnew-parent-branch>

Rebase specific feature:

arh rebase --feature \x3Cfeature-branch-name>

Rebase entire stack:

arh rebase --base \x3Cbase-branch>

Rebase subtree:

arh rebase --subtree \x3Csubtree-root>

Rebase all features:

arh rebase --all

7. Discarding Features

Discard a feature branch:

arh discard -f \x3Cfeature-name>

Important: This deletes both local and remote branches. Any PRs open from this branch will be closed.

Discard local only (keep remote):

arh discard --skip-remote -f \x3Cfeature-name>

Use --skip-remote when checking out someone else's PR branch that you want to discard locally.

8. Cleaning Up Merged Features

Clean up merged/closed feature branches:

arh tidy

Clean up without prompts:

arh tidy --no-interactive

How it works:

• Lists all closed/merged features
• Asks for confirmation to discard
• Updates upstream tracking for dependent branches
• Example: main -> A -> B -> C, if B is closed, tidy discards B and updates C's parent to A

9. Running Quality Checks

Run linters on changed files:

arh lint

Run tests on changed files:

arh test

10. Version Management

Check arh version:

arh version
# or
arh -v

Common Workflows

• New feature: arh feature NAME -> commit -> arh publish
• Stacked PRs: arh feature NAME -> commit -> arh feature next NAME2 -> commit -> arh publish --full-stack
• Update after review: commit fixes -> arh publish --no-interactive
• Merge stack: arh checkout last -> arh merge -> arh tidy
• Rebase on main: arh rebase or arh rebase --all, then arh publish --no-interactive

Troubleshooting

PR publish fails due to lint errors:

arh publish --apply-fixes  # Auto-apply lint fixes

Skip pre-push coverage check (/opt/uber/etc/custom-hooks/coverage-check.sh):

arh publish --no-coverage             # Skip coverage via wrapper (preferred)
SKIP_COVERAGE=1 arh publish           # Skip coverage via env var
COVERAGE_THRESHOLD=70 arh publish     # Lower threshold (default: 80%)

The --no-coverage flag is handled by an arh() shell wrapper in ~/.aliases that creates a marker file (/tmp/.skip-coverage-$(id -u)) consumed by the pre-push hook. Aliases: arh-nc (no coverage), arh-lc (lower threshold) — also in ~/.aliases.

Feature tree is messy:

arh -s              # Check status
arh tidy            # Clean up merged features
arh rebase --all    # Rebase everything

Cannot merge due to failing checks:

• Check build status: arh -s
• Ensure all required approvals are received
• Verify all builds are passing
• Fix issues and update PR: arh publish

Tips

• Always create features with arh feature for proper parent tracking
• Use arh -s frequently to monitor PR status
• Use --no-interactive in automated/CI contexts
• Use --changes-planned for WIP/draft PRs
• Run arh tidy regularly to keep feature tree clean
• Use --full-stack for dependent changes
• go-code monorepo: After git pull or arh pull, MUST run git-bzl refresh