PR to Green

This skill provides a deterministic maintainer workflow for taking an in-flight PR branch to green.

When to use

• A PR is behind main and needs sync/rebase
• There are merge conflicts to resolve intelligently
• Remote checks are failing (tests, docs, lint, or packaging)
• You need a concise update for the PR describing what was fixed and what remains

Preconditions

• Confirm branch and remotes before making git changes
• Preserve user/unrelated local modifications; never discard unknown work
• Use CausalPy environment commands:
  • $CONDA_EXE run -n CausalPy <command>
• For PyMC/PyTensor/matplotlib imports and test commands, request full permissions as needed

PR number entrypoint (manual invocation)

If the user provides a PR number (for example PR #724), do this first:

1. Resolve PR metadata from GitHub
   • gh pr view <number> to get title, state, head branch, base branch, mergeability, and check summary.
   • gh pr checks <number> to get per-check pass/fail/pending status.
2. Move local repo to the PR branch
   • gh pr checkout <number> (preferred) so local branch tracks the PR head.
3. Verify branch context before edits
   • Confirm current branch, tracking status, and whether local uncommitted work exists.
4. Continue with the main workflow below using the PR base branch from GitHub metadata (not assumptions about main).

Workflow

1. Triage and early exit

   • Assess PR state from entrypoint metadata: branch divergence, mergeability, and check results.
   • If the PR is up-to-date with its base branch, has no conflicts, and all remote checks pass:
     • Report "PR is green — no action needed" and stop.
   • Otherwise, classify what needs fixing: behind-base, conflicts, failing checks, or a combination.

2. Sync branch with base

   • Prefer git fetch upstream then git rebase upstream/<base-branch> (or maintainer-preferred merge strategy).
   • If the PR cannot be checked out, report the blocker and ask for maintainer guidance.
   • Resolve conflicts file-by-file with intent preservation.
   • Re-run targeted checks after conflict resolution to detect semantic drift.

3. Fix failing checks with smallest valid change

   • Lint/type: apply minimal code changes, avoid broad refactors.
   • Tests: patch root cause and add/adjust tests under causalpy/tests/ if behavior changes.
   • Docs/doctest: follow docs placement and glossary/citation conventions.
   • Packaging/release checks: verify version and install/import expectations.

4. Re-run checks in escalating scope

   • Fast local signal first (targeted tests/lint).
   • Then full gate commands required by project norms.
   • Always run prek run --all-files before final handoff.
   • If fixes introduced new failures, loop back to step 3 with the new failure set. Do not push until a full local pass is achieved or blockers are identified.

5. Push and verify remote

   • Push fixes to the PR branch (git push).
   • Monitor remote checks via gh pr checks <number> until they complete or a timeout is reached.
   • If remote checks fail on issues not reproducible locally, note the discrepancy explicitly.

6. Prepare maintainer-ready status update

   • What was failing.
   • What changed to fix it.
   • Which checks now pass (local and remote).
   • Remaining blockers (if any) and exact next steps.

Subagent delegation

Use subagents (via the Task tool) when work is noisy, broad, or high-risk. Each subagent runs in its own context window and returns a condensed result.

ci-failure-investigator

Trigger when CI logs are long/noisy, failures span multiple jobs, or failure family is unclear.

Handoff (include in Task prompt):

• PR number and branch name
• Failed job names and relevant log snippets or gh run view output
• Ask for: root cause ranking, fix-first order, and minimal patch plan

merge-conflict-analyst

Trigger when rebase/merge produces non-trivial conflicts, intent differs across branches, or conflict count is high.

Handoff (include in Task prompt):

• Target branch and merge/rebase direction
• Full conflict list (git diff --name-only --diff-filter=U) and key conflict markers/snippets
• Ask for: conflict risk map, lowest-risk resolution order, and explicit escalations

Maintainer escalation clause (required)

Do not auto-resolve and continue silently when conflicts are highly complex. Instead, stop and request maintainer input with a brief report.

Escalate by default when:

• .ipynb conflicts are messy (overlapping cell content plus metadata/output churn)
• conflict resolution would drop one branch's meaningful behavior
• conflicts touch core contracts and intent is ambiguous (experiments/models/tests/docs all changed around same behavior)

Escalation report must include:

• conflicted file list and risk class
• resolution options (1-2) with trade-offs
• recommended next step and what decision is needed from maintainer

Scope drift / upstream compatibility escalation (required)

Do not keep patching silently when greening a PR turns into broader compatibility work outside the PR's feature surface. Stop after root-cause identification and ask the maintainer whether to continue in the PR or split the work into a separate branch/PR from main.

Escalate by default when:

• the failing checks are caused by third-party API or version drift in shared/core code
• the fix would benefit multiple open PRs or the default branch, not just the current PR
• the next fix would modify shared integrations beyond the feature the PR is introducing
• successive CI reruns keep exposing new failure families outside the original PR scope

Scope-drift report must include:

• the original PR goal and the newly discovered broader issue
• which files are feature-specific versus shared/core compatibility files
• options: patch in the PR, split a separate compatibility PR, or pause for maintainer direction
• the recommended next step and why

CausalPy guardrails

• Never use destructive git commands unless explicitly requested
• Do not create ad hoc test scripts; use pytest tests in causalpy/tests/
• Keep PyMC-heavy tests runtime-controlled via sample_kwargs
• Keep docs/notebooks in correct locations and formats
• If checks cannot be run, report exactly what was skipped and why