arthai-marketplace

Tutorial: Ship Your First PR

In this tutorial you’ll take a small code change from your working tree to a merged-ready GitHub PR using three skills: /precheck → /qa → /pr. By the end you’ll understand the toolkit’s standard ship path and what each gate protects you from.

Time: ~10 minutes You need: the toolkit installed (Getting Started), a project with a test suite, and a small change you’re ready to ship.

Step 1: Get on a feature branch

Both /precheck and /pr refuse to run on main — the toolkit never pushes to your default branch. If you’re on main, branch first:

git checkout -b my-first-change

Make your small change now if you haven’t already — a one-line fix or a comment tweak is fine for a first run.

Step 2: Run the fast local gate

/precheck

This catches CI failures locally in ~30 seconds instead of a 4-minute CI round-trip. You’ll see:

  1. A revert-safety check — verifies your working tree doesn’t accidentally undo a recently-merged PR (a stale editor buffer or bad stash-pop can do this silently).
  2. The test suites relevant to your changed files — it diffs against main and picks only the suites that cover what you touched.

On success the run ends with:

✓ Precheck passed (N tests, Xs) — Ready to push.

It also writes a pass marker at .claude/.precheck-passed — /pr checks this before allowing a PR.

Note: on a passing run, /precheck doesn’t stop at a pass marker — it carries straight through the full ship sequence on its own: commit → push → PR → merge → branch cleanup, with no /qa or /pr review in between. If you want to follow the guarded /qa → /pr path in this tutorial (recommended for anything beyond a trivial change), interrupt it before it merges, or run /qa and /pr yourself instead of /precheck. If you let it run to completion, your change is already merged to main — skip ahead to What you learned.

If precheck fails, it removes any stale pass marker and lists the failing tests — it will not push with failures. Fix them and re-run.

Step 3: Run QA on your change

/qa

With no argument this runs commit mode — targeted checks on exactly what you changed (~1–3 minutes). You’ll see a mode line confirming commit mode, then 2–4 QA agents running targeted checks on your changed files, generating 5–8 fresh test scenarios that think like a real user about what your change could break.

The run ends with a structured QA report: pass/fail per check, any failures or warnings, coverage gaps (new code without tests), and a suggested next step. On pass, it asks whether to run /review-pr now or skip to /pr — that’s a deliberate confirmation checkpoint, not a glitch.

If you run /qa and nothing has changed since the last commit, it shows a one-line picker instead of running — commit your change first, or pick a different mode.

Step 4: Create the PR

/pr

This is the full safe path to a PR. You’ll see, in order:

  1. A revert check (advisory — it asks before proceeding if anything looks suspicious)
  2. /qa in commit mode as a hard gate — no PR is created on a failing QA run
  3. A commit in your project’s detected style (it reads CLAUDE.md and git history to match your team’s conventions; it never stages .env, credentials, or large binaries)
  4. A tracking issue found or created, so the PR auto-closes it on merge via Closes #N
  5. Your branch rebased on the latest default branch and pushed (it fails loudly on conflicts — never auto-resolves)
  6. A PR URL with Summary, QA Results, and Test plan sections

Step 5: After the merge

When the PR is merged, tell the session “merged” (or let a configured Monitor watcher detect it). /pr then verifies the issue closed, deletes the remote and local branches, checks out main, pulls, and runs /onboard so you know what’s next.

What you learned

Next tutorial: Calibrate a project — teach the toolkit your codebase so every workflow gets smarter.