pairit

Files (2)

• SKILL.md
• safe_merge.sh

SKILL.md (first lines)

# pairit: tests from a partner, code from the driver, one reviewer, merge the PR

**Why a partner writes the tests:** tests written in the same context as the code share its blind spots.
Tests written first by another context, from the issue, do not.

**The check** is what CI runs; run it from the worktree:
```bash
.venv/bin/python -m pytest -q && .venv/bin/ruff check src/ tests/
```
**Fast local check** (#1248), for iterating: `scripts/check_delta.sh [BASE]` (default `origin/main`) runs only
the tests `scripts/py_delta.py` vouches for (routed by `scripts/py-delta.conf`) on the commits since the merge
base, then ruff. It falls back to the full suite whenever py_delta cannot vouch for a subset (a dirty tree, a
code change, any doubt). It is local only: GitHub CI still runs the full suite on every Python, and the merge
gate is unchanged. It runs the branch's own `py_delta.py` and `py-delta.conf`, so a branch that edits them
vouches for itself; CI's full suite stays the authority.

pytest's `pythonpath = ["src"]` means a worktree's tests import that worktree's `src`, even with the shared
`.venv`. To run the CLI from a worktree, use `PYTHONPATH=/tmp/yk-<N>/src .venv/bin/yurtle-kanban …`.

```text
0. BRANCH  a worktree + branch from origin/main
1. TESTS   the test partner (a fresh Agent sub-agent) writes pytest tests from the issue → commit T, proven RED
2. CODE    the driver writes code to GREEN without editing T's tests, adds a changelog.d/ fragment, runs the check
3. REVIEW  push, open the PR, and a DISTINCT reviewer session posts a verdict comment; after `changes`
           (blocking findings) the fixes go back to it for a fresh approve at the fixed head (#1228)
4. MERGE   approve at head, or an approve round's fixed tip (`fixes-at-sha:`), + CI green →
           `safe_merge.sh <P>`; the issue closes through `Fixes #N`
```

**0. Branch.** Use `fix/` for a bug, `feat/` for a feature and `chore/` for anything else.
```bash
git fetch -q origin main
git worktree add -b fix/<N>-<slug> /tmp/yk-<N> origin/main
ln -s "$PWD/.venv" /tmp/yk-<N>/.venv
```
Every later step uses the literal path `/tmp/yk-<N>`.

**1. The partner's brief** (Agent tool, fresh context). Give it these lines verbatim:
- *"Read issue #<N> (`gh issue view <N>`). Write tests for what the issue SAYS — its repro and its Expected
  section — not for how you would fix it. Work only in /tmp/yk-<N>."*
- *"pytest, in a NEW file `tests/issues/test_<N>_<slug>.py` (module docstring naming the issue); import or
  copy the fixtures you need from the owning module's tests. Never append to a shared test module: a new
  file can't conflict with a parallel PR. Reproduce the issue's own commands through `CliRunner` where it
  gives CLI steps. Add a negative control, where one applies, that must stay green."*
- *"Commit the tests ALONE as `test(#<N>): red`. Run them and confirm they are RED for the RIGHT reason (an
  assertion, never an import or fixture error), and that the rest of the suite is still green. Return the
  sha, the paths and the failing test names."*

If the issue can't be reproduced on `origin/main` (it's already fixed, or the repro is wrong), the partner
says so and commits nothing. Comment the finding on the issue, then close it or label it `needs-decision`.

**2. Code to green.** Never edit T's test files; if a test is wrong, send it back to the partner. Keep the
change the smallest one that fixes the issue. Match the surrounding code: type hints, comment density,
existing helpers (`_add_or_update_frontmatter_field`, `PRIORITIES`, …). Add a changelog fragment
`changelog.d/<N>.md` (first line `<!-- section: Fixed -->`, or Added…; see `changelog.d/README.md`) that
names `(#<N>)`. Never edit `CHANGELOG.md` itself; the release assembles the fragments. Run the check. The
80 ruff findings in `tests/` are known, and CI lints only `src/`.

**3. The review, by a DISTINCT session.**
```bash
git -C /tmp/yk-<N> fetch -q origin main
git -C /tmp/yk-<N> -c core.commentChar=';' rebase origin/main   # see "Rebased" below
git -C /tmp/yk-<N> push -q --force-with-lease -u origin HEAD   # the rebase rewrote the branch
gh pr create --head <branch> --title "<type>: <what> (#<N>)" --body "Fixes #<N>. …"
claude --dangerously-skip-permissions -p "$(cat <brief file>)" < /dev/null   # run it in the background
```

**Build each brief from explicit values** (PR number, issue number, branch, the full head sha, the tests
commit), written into a template by a small script. Never make it by running `sed` over an earlier brief:
a substitution like `s/115/117/` also rewrites digits inside the sha, and the reviewer then checks out a
commit that doesn't exist. Before launching, grep the brief for the full sha.
End the PR body with the attribution line from the session's system reminder.

The brief tells the reviewer to:
- review PR #<P>, branch `<branch>` at tip `<SHA>`, in its OWN scratch worktree
  (`git worktree add /tmp/yk-rev-<P> <SHA>` plus the `.venv` symlink), read-only on the branch;
- check that the tests in `<T>` match the ISSUE, not the code;
- confirm `git diff <T>..<SHA> -- <T's test files>` is empty;
- confirm the code doesn't special-case the tests;
- mutate the code at two points and see a test go red each time;
- re-run the issue's own repro against the branch (`PYTHONPATH=…/src .venv/bin/yurtle-kanban …`);
- check every caller of each changed function for regressions, and confirm the check is green;
- post ONE PR comment (`gh pr comment <P> --body-file …`) whose first line is `reviewed-at-sha: <SHA>` and
  second line `verdict: approve|changes`, followed by findings with `file:line` and a failure scenario.
  Non-blocking findings are marked `(follow-up)`. The comment's first bytes must be
  `reviewed-at-sha:`, with no leading whitespace or BOM: `safe_merge.sh` reads only that first line,
  and a verdict it can't read counts as no verdict.

**Review rounds** (#987, tightened by the Captain 2026-10-01, #1228: blocking findings get re-reviewed).
- `verdict: approve` → merge (step 4). Its non-blocking `(follow-up)` findings may be fixed first: run the
  check, push, and post ONE PR comment whose first two lines are `fixes-at-sha: <FIX-SHA>` and
  `for-review-at: <REVIEWED-SHA>` (both full 40-hex shas, exactly as the verdict names it; the fixed tip must
  be a later commit), then one line per finding → its fix commit. `safe_merge.sh` merges that tip once CI is
  green (the reviewed sha must be an ancestor of it, and the last verdict before the fixes comment, at any
  sha, must be that unedited `approve`: a `changes` after it means a fresh approve at the head); the picker
  counts it as reviewed. Follow-ups not fixed now are filed as issues.
- `verdict: changes` → its findings are BLOCKING. Hand EVERY finding to the implementer (a fresh Opus sub-agent,
  or the one that wrote the code) in one message; a finding about a test goes to the test partner as a ruled
  test edit, in its own named commit. Each fix commit names the finding it closes (`fix(#<N>): r1 F<n> — …`);
  a behaviour fix carries a test that goes red without it. Run the check, push, then send the fixed head BACK
  TO THE REVIEWER (the same session may re-verify; it checks each finding is really fixed, not just claimed),
  which posts a NEW `reviewed-at-sha: <fixed head>` / `verdict: …`. A `fixes-at-sha` comment after `changes`
  does not make a head mergeable: the gate needs that fresh approve.
- Escalate instead of merging only when a finding cannot be closed by a tested fix: it needs a Captain ruling,
  changes the issue's scope, or the driver disputes it. Comment why on the issue and park both:
  `gh issue edit <N> --add-label needs-decision` and `gh pr edit <P> --add-label needs-decision`. The picker
  skips a held PR.

Partner, implementer and fixes run as in-session Opus sub-agents (the `Agent` tool); GLM is not used.

The verdict comment is posted under the same GitHub account as the PR, so GitHub can't enforce reviewer ≠
author. The distinct `claude -p` session is what makes the review independent, and the comment's author
proves nothing.

**4. Merge** (from the main checkout):
```bash
bash .claude/skills/pairit/safe_merge.sh <P>  # waits for CI; reads the PR head ONCE; refuses
                                              # unless EVERY check is SUCCESS or SKIPPED,
                                              # origin/<branch> is that head, it merges

From Congruentsys/yurtle-kanban, MIT.

More from Congruentsys/yurtle-kanban