Commit, Push, and Ensure CI Passes

Commit changes, run local validation, push to remote, open a draft PR if needed, and ensure CI passes.

Workflow

1. Pre-Commit Cleanup

Before running validation, clean up your changes:

• Remove comments and docstrings you added (user instructions take precedence if they want docstrings)
• Remove try-except blocks that suppress errors—code should fail early rather than log warnings and potentially behave incorrectly. Exception: when aggregating results from multiple operations to report at the end.
• Move imports to top of file

2. Run Local Validation

Before committing, run all local checks:

Linting, Typechecking, and Formatting:

• Run the project's linter (e.g.,

  ruff check

  ,

  eslint

  ,

  golangci-lint

  )
• Run the typechecker (e.g.,

  basedpyright

  ,

  mypy

  ,

  tsc --noEmit

  )
• Run the formatter (e.g.,

  ruff format --check

  ,

  prettier --check

  ,

  gofmt

  )
• Fix any issues found before proceeding

Tests:

• Check if the project has slow tests marked with

  @pytest.mark.slow

  (search for

  mark.slow

  in test files)
• If slow tests exist: run

  pytest -m "not slow"

  for fast tests, then run affected slow tests
• If no slow test markers exist, run all tests:

  pytest

  ,

  npm test

  ,

  go test ./...

• To identify affected slow tests, check which test files import or exercise modified code
• If pytest-xdist is available (

  uv pip show pytest-xdist

  ), use

  -n auto

  for parallel execution:

  pytest -n auto -m "not slow"  # fast tests in parallel
  pytest -n auto path/to/slow_test1.py path/to/slow_test2.py  # affected slow tests in parallel
  

3. DVC (Data Version Control)

If this is a DVC-tracked repository (has

.dvc

files or

dvc.yaml

):

• Run

  dvc repro

  to reproduce any affected pipelines
• Run

  dvc push

  to push data artifacts to remote storage
• This prevents

  check-dvc

  CI failures

Fixing

check-dvc

CI failures:

1. Run

   dvc status --remote

   to see which files are missing
2. Run

   dvc push

   to upload missing files to the remote
3. Commit any updated

   .dvc

   files if they changed

3b. Pivot (Pipeline Management)

If this is a Pivot-tracked repository (has

.pvt

files or

pipeline.py

):

• Run

  pivot run

  to execute any outdated pipeline stages
• Run

  pivot push

  to push outputs to S3
• Commit any updated

  .pvt

  or

  .pivot/stages/*.lock

  files
• This prevents

  check-pivot

  CI failures

Fixing

check-pivot

CI failures:

1. Run

   pivot status

   to see which stages need to run
2. Run

   pivot run

   to execute outdated stages (or

   pivot run stage_name@variant

   for specific stages)
3. Run

   pivot push

   to upload outputs to S3
4. Commit any updated

   .pvt

   or

   .pivot/stages/*.lock

   files

4. Commit and Push

Once local validation passes:

1. Run

   git status

   and

   git diff

   to see changes
2. Run

   git log --oneline -3

   to match commit message style
3. Stage changes with

   git add

4. Create commit with descriptive message ending with:

   Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
   

5. Push to remote with

   git push

5. Check if on Main Branch

Determine if you're pushing directly to the main branch:

current_branch=$(git branch --show-current)
main_branch=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | xargs)

if [ "$current_branch" = "$main_branch" ]; then
  # Pushing directly to main - skip PR creation, go to step 10
  echo "On main branch, skipping PR workflow"
fi

If on main/master: Skip steps 6-9 and go directly to step 10 (Wait for CI on Direct Push).

If on a feature branch: Continue with step 6.

6. Determine PR Base Branch (Feature Branches Only)

Before creating a PR, determine the correct base branch:

# Get the main/master branch name
main_branch=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | xargs)

# Find the merge-base with main
merge_base=$(git merge-base HEAD origin/$main_branch)

# Check if there's another branch between current branch and main
# This finds branches that contain the merge-base but are not main
intermediate_branch=$(git branch -r --contains $merge_base | grep -v "origin/$main_branch" | grep -v "origin/HEAD" | head -1 | xargs)

# If an intermediate branch exists and is an ancestor of HEAD, use it as base
if [ -n "$intermediate_branch" ]; then
  base_branch=${intermediate_branch#origin/}
else
  base_branch=$main_branch
fi

Use

$base_branch

as the PR base instead of always using main/master.

7. Open or Update Draft PR (Feature Branches Only)

Check if the current branch has an open PR:

gh pr view --json number,url,state,isDraft 2>/dev/null

If no PR exists:

• Create a draft PR targeting the correct base branch:

  gh pr create --draft --base $base_branch --title "..." --body "..."
  

• Assign the PR to Thomas Broadley:

  gh pr edit --add-assignee tbroadley
  

• Add an OKR label (choose the most relevant from available labels starting with

  OKR-

  ):

  # List available OKR labels
  gh label list --search "OKR-"
  # Add the appropriate label using the API (gh pr edit --add-label can fail due to deprecated Projects classic)
  gh api repos/{owner}/{repo}/issues/{pr_number}/labels -f "labels[]=okr-..."
  

If PR exists but is not a draft:

• Continue with the existing PR

8. Wait for CI and Ensure It Passes (Feature Branches Only)

First, check if the repo has GitHub Actions workflows:

# Check for workflow files
if ! ls .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | head -1 > /dev/null; then
  echo "No GitHub Actions workflows found, skipping CI wait"
  # Skip to step 9
fi

If no workflows exist, skip waiting for CI and proceed to step 9.

Before waiting for CI, check for merge conflicts:

Merge conflicts prevent CI from running. Check immediately after pushing:

gh pr view --json mergeable,mergeStateStatus

• If

  mergeable

  is

  false

  or

  mergeStateStatus

  is

  DIRTY

  , there are merge conflicts
• If

  mergeable

  is

  UNKNOWN

  , wait a few seconds and check again (GitHub is still computing)

If merge conflicts exist, resolve them before waiting for CI (see "If CI cannot run" below).

If no conflicts, monitor CI status:

gh pr checks --watch

If CI cannot run (e.g., merge conflict):

1. Identify the blocker:

   gh pr view --json mergeable,mergeStateStatus

2. If merge conflict:

   git fetch origin $base_branch
   git rebase origin/$base_branch
   # Resolve conflicts
   git add .
   git rebase --continue
   

3. Run local validation again (steps 1-2)
4. Force push:

   git push --force-with-lease

5. Wait for CI again

If CI fails:

1. Check which jobs failed:

   gh pr checks

2. Get failure details:

   gh run view <run_id> --log-failed

3. Fix the failing tests/checks locally
4. Run local validation again (steps 1-2)
5. Commit the fixes and push
6. Repeat until CI passes

9. Respond to PR Comments (Feature Branches Only)

IMPORTANT: Never leave top-level comments on the PR (via

gh pr comment

or the issues comments API). Only reply directly within review comment threads using the replies API. Top-level comments like "Addressed review feedback" clutter the PR.

If there are existing PR review comments, check if pushed changes address them.

Fetch review comments:

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate

For each unresolved comment that was addressed:

1. Leave a reply:

   gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \
     -f body="Claude Code: <explanation of how this was addressed>"
   

2. Resolve the thread:

   gh api graphql -f query='
     mutation {
       resolveReviewThread(input: {threadId: "<thread_id>"}) {
         thread { isResolved }
       }
     }
   '
   

To get thread IDs:

gh api graphql -f query='
  query {
    repository(owner: "{owner}", name: "{repo}") {
      pullRequest(number: {pr_number}) {
        reviewThreads(first: 100) {
          nodes {
            id
            isResolved
            comments(first: 1) {
              nodes {
                id
                databaseId
                body
              }
            }
          }
        }
      }
    }
  }
'

Re-request review: After addressing all comments from a reviewer, request their re-review:

gh pr edit --add-reviewer <reviewer-username>

To find reviewers who left comments:

gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews --jq '.[].user.login' | sort -u

10. Wait for CI on Direct Push (Main Branch Only)

First, check if the repo has GitHub Actions workflows:

# Check for workflow files
if ! ls .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | head -1 > /dev/null; then
  echo "No GitHub Actions workflows found, skipping CI wait"
  # Task complete - no CI to wait for
fi

If no workflows exist, the task is complete.

If workflows exist, monitor CI using the workflow run:

# Watch the CI run for the latest commit
gh run watch

If CI fails:

1. Check which jobs failed:

   gh run view --log-failed

2. Fix the failing tests/checks locally
3. Run local validation again (steps 1-2)
4. Commit the fixes and push
5. Repeat until CI passes

Notes

• Always run local validation before pushing to catch issues early
• Steps 6-9 only apply to feature branches (not main/master)
• Step 10 only applies when pushing directly to main/master
• Only respond to PR comments that were actually addressed by the changes
• Prefix all GitHub comments with "Claude Code: "
• If CI keeps failing after multiple attempts, report the issue to the user
• The goal is green CI before considering the task complete (on a draft PR for feature branches, or on the commit for direct pushes to main)