Open PR

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. 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 evidence. If a finding changes scope or the intended behavior, surface that decision instead of quietly expanding the task.

Do the checks available to you. Ask the engineer only for missing access, a behavior decision, or experience/judgment you cannot supply. Reuse their earlier vetting when it still covers the outcome; do not add a ritual sign-off question. Never claim the engineer personally used or approved something because an agent did it. Surface material gaps with what remains to be checked and why.