Choruz PR

Opening a pull request

When loaded from a personal skills directory, resolve repository links from this skill's canonical .agents/skills/choruz-pr/ location in the active Choruz checkout, not from the installed copy.

The rule of this repository (docs/testing/pr-test-policy.md): CI runs what the changed paths need; the type you declare tells reviewers what tests to expect and labels can only add gates. This skill walks a change from "done on a branch" to "merged" without a person having to babysit it.

1. Classify the change

Pick one type from the policy table and keep it in mind for every later step:

If the diff spans two types, use the stricter row. Never pick docs or chore to avoid tests: CI reads paths, not the type, so it does not help.

For feature, api / database and security / auth, walk the seams in docs/adding-a-feature.md before writing tests, and fill the template's "Seams touched" section from that walk. A seam left unchecked carries a one-line reason ("no new table", "core route, no plugin gate"); the reviewer reads the section against the diff.

2. Prove the affected behaviour

Do this before anything else. A bugfix without a failing-then-passing regression test is not ready. Put e2e coverage next to the feature's spec so select_e2e_specs.py picks it up (add a rule there when you add a spec for a new feature area).

Apply the policy's behaviour acceptance evidence before selecting tests: name the observable contract, trace its production entry to the owner of the result, and select only the ordinary scenarios affected by the change. Read the assertions, not just test names. Record the scenario, boundary replacements and observed red/green evidence in the PR; document unavailable evidence without calling it passed. An existing test that stays green when the claimed behaviour is absent does not satisfy the type's requirement.

Before adding coverage, apply the policy's test value and incremental cost: find and strengthen the existing owner first, explain what a new scenario uniquely proves, and replace affected obsolete or redundant coverage without losing guarantees. This is scoped to the change, not a mandatory whole-suite cleanup.

Naming new packages and files

Rust packages are choruz-<role>: directory equals the package name, the crate ident is choruz_<role>. npm packages are @choruz/<role>. Libraries live in crates/, long-running processes in services/, human entry points (choruz-cli, choruz-replay, web) in apps/. Files: Rust snake_case.rs, web kebab-case.ts(x), tests beside the module (foo.test.ts, tests/<topic>.rs), migrations V0NN__name.sql. A name states a role, never a layer or a generic word.

3. Independently audit the change

Before simplify, delegate a read-only audit to one independent GPT-5.6 Terra agent (gpt-5.6-terra) that did not implement the change. Explicitly select this model for the first audit and every re-audit; never inherit the author's model. Have it read and use choruz-pre-simplify-audit, which owns the criteria for skill execution evidence, code structure and test effectiveness.

Supply the user request and constraints, base/head revisions, current diff including relevant uncommitted and untracked files, actual command results or artifact paths, and prior findings. Never send credentials. The auditor independently determines applicable requirements; reading skills alone is not proof they were executed.

If the verdict is FAIL or UNVERIFIED, the implementer resolves the due-now gaps and supplies updated code and evidence. Repeat audit → remediation → re-audit until the auditor explicitly returns PASS before entering simplify. Prefer the same auditor; a replacement must also use gpt-5.6-terra and receive prior findings. The implementer cannot self-certify closure.

Missing access, unavailable delegation or an unavailable Terra model leaves the gate unverified: report the blocker, do not silently substitute self-review or another model. The auditor does not edit, push, merge or recursively delegate. Keep the verdict and reviewed diff identity in the PR's existing evidence section. This gate does not replace simplify, tests or final CI.

4. Simplify the diff

Run /simplify on the branch (or review the diff yourself if the skill is not available): remove dead code, extra abstractions and stray debug output the work left behind. Commit the result.

5. See what CI will run, and run it locally

choruz-pre-push-checks owns the selection rules; the short version:

bash .agents/skills/choruz-pr/pr-plan.sh

It uses the same selectors as the workflow's Detect changes job and prints two lists: the CI jobs this change triggers, and the commands to run locally first. Run those commands. A red job on the PR that you could have caught locally costs a CI round trip and a reviewer's trust.

Local e2e needs the host stack (infra/host/web_e2e.sh starts PostgreSQL, the API, the pipeline and the web app itself); see docs/testing/pr-test-policy.md.

If simplify or a later fix changes the reviewed scope or invalidates evidence, have the independent agent recheck the affected requirements and rerun the affected checks. An earlier verdict does not certify a different diff.