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.