/open-pr

name: open-pr
description: Prepare arcade-mcp changes for review by verifying intended behavior, filling the repository PR template, and creating or updating the PR. Use for "open a PR", "get this reviewed", or "make this PR ready". Resume existing work. PR preparation is separate from releasing; use a code-review skill for review-only requests.

Open a PR

Deliver a focused PR with an accurate description and evidence supporting its intended behavior. The author owns the job, behavior, approach decisions, and outcome, and stays responsible for AI-assisted work; line-by-line recall is not a prerequisite.

Follow `CLAUDE.md` and `.github/PULL_REQUEST_TEMPLATE.md`. Link issues and design discussions rather than reconstructing them in the PR.

Use the GitHub and issue-tracker tools the user chose. Discover available operations before assuming a CLI, connector, or credentials exist. Keep local git operations local. If a needed remote operation is unavailable, finish local preparation and report the exact missing capability; do not silently switch tools or claim the operation succeeded.

1. Establish the actual state

• Read `CLAUDE.md` and the PR template. Inspect the working tree, staged changes, branch, upstream, remotes, and any existing PR. Confirm the destination repository and base; use the existing PR's base or `main` unless the task specifies otherwise. Fetch the base before assessing the diff.
• Review both the committed diff against the merge base and pending changes. Identify the intended scope, related issue, and consequential choices. Preserve unrelated work; stage explicit files or hunks. Do not reset, squash, rebase, or force-push someone else's work to tidy the PR.
• Apply [PR scope discipline](../../rules/pr-scope.md). Resolve an actual scope problem rather than expanding the description to explain unrelated work.
• Reuse a matching open PR. A closed or merged PR is not an update target. If the branch is detached or is the base branch, create a task branch. Resolve ambiguity that could send work to the wrong repository, base, or PR before publishing.
• Find the tracking issue (GitHub issue or Linear) in task context, branch, commits, or existing PR and verify it describes this work. If none exists, file one first (or stop and ask your human to if you cannot). Do not borrow an unrelated or closed issue.

A request to open a PR authorizes routine commits, pushing the task branch, and creating a Draft. A request to get work reviewed also authorizes marking it ready once vetted; preserve an existing Ready state. Honor text-only requests. Merging, reviewer assignment, and releasing require the corresponding user request; do not expand "open a PR" into those actions.

2. Establish confidence in the behavior

Use the issue and linked discussion as the expected behavior. The implementation and tests are evidence to examine, not the source of truth for what should happen. If those sources conflict, identify the concrete decision needed rather than silently rewriting the contract to fit the code.

Load only the relevant entry points:

• **Behavior:** the issue, `CLAUDE.md`'s architecture notes for the touched area, and docs the change affects. Note whether the change touches the MCP side (`MCPServer`, transports), the Arcade Worker side (`libs/arcade-serve/`), or both through the shared `ToolCatalog` / `create_arcade_mcp()`.
• **Checks:** `make check` (pre-commit + mypy per lib) and `make test`, or targeted `uv run pytest libs/tests/<area>/...` while iterating; CI runs `.github/workflows/main.yml` on Python 3.10–3.14 across Linux, macOS, and Windows. Changes to `arcade-core` or `arcade-tdk` need checks for the libs that depend on them. Always use `uv run`, never bare `python` or `pip`.
• **Versioning:** bump the touched library's version in its `pyproject.toml` once per branch (check `git diff main` first), and raise the dependency floor in dependent libs for breaking cross-library changes. `release-on-version-change.yml` publishes on version changes, so a bump is a release decision; call it out.

Choose verification proportional to the change:

• Exercise the affected workflow for real. For server or tool changes, run a server from `examples/mcp_servers/` with `arcade mcp stdio` or `arcade mcp http` (or MCP Inspector) and drive the changed path; for worker changes, call the `/worker/*` endpoints with `ARCADE_WORKER_SECRET` set; for CLI changes, run the command. Check the normal path and plausible boundary, failure, or regression paths. Anything reachable from the stdio transport must leave stdout/stderr clean. Documentation changes need rendering/link checks, not unrelated suites.
• Inspect whether tests would catch the claimed failure or a wrong implementation. For a bug fix, demonstrate the regression fails before and passes after when feasible. Watch for weakened assertions, excessive mocks, or tests that repeat the implementation. Every behavioral change needs a test in `libs/tests/`; do not invent additional tests for trivial, reversible changes.
• Run required checks and affected suites. Confirm the intended tests actually ran: zero collected tests, a deselecting `-k`, or skipped tests (evals tests skip without `anthropic`/`openai` installed) prove nothing. Record revision, command, observed result, and limits in working notes; put only the useful summary in the PR. Reuse applicable evidence; rerun checks affected by edits, including formatter changes before committing.
• Review the final diff for unintended changes, unsafe boundaries, and reuse of established patterns. For substantive changes, use a code-review skill or a fresh reviewer context with the intended behaviors, relevant constraints, and raw diff. Do not feed it an assurance that the change is correct. Reuse an applicable independent review already completed; add another only for an unresolved risk.
• Verify findings against code or a reproduction before fixing them. Reject false positives with evide