PR Raise

When the user is ready to open a pull request from a feature branch. Runs the local code review (the compass-code-review-pr skill) on the change, raises the PR with compass pr create, and posts an @claude comment to trigger the on-demand review.

By the time this skill runs, the work is done from the developer's side — review is a post-done validation activity, not a continuation of implementation. That means task/story bookkeeping (see compass-agile-close-task) happens before this skill, not after review approves. A PR should never need a bookkeeping-only commit once CI has gone green post-review — that wastes a full CI cycle for a change with no code content. See Work a task through to merged PR for why the lifecycle is ordered this way.

1. MANDATORY — classify the change and run only the matching checks locally first, and do not skip this even under time pressure. CI gates a PR on drift and lint alone. Four path-filtered workflows run on pull_request: codegen-drift.yml, doc-lint.yml, shell-script-drift.yml, and template-drift.yml. Each one fires only on its own paths, and none of them builds or tests: the workflows that compile the C++ and run ctest (continuous-*.yml, nightly-*.yml) run on a schedule, not on a PR. So this step is the only thing that catches a broken build before review, and the PR description is the only record that it happened.

   Classify the diff against its branch point:

   git diff origin/main...HEAD --name-only
   

   Bucket every changed file with the rule table. A mixed change runs the union of its classes' checks:

   Class	Paths	Checks to run
   docs	doc/*, assets/*, .claude/*, *.md, *.org, projects/*/modeling/* (org/puml/png), external/* (vendored)	Site check (+ codegen drift when projects/*/modeling/* changed)
   code (C++)	projects/ores.* C++ sources and headers, *.cmake, CMakeLists.txt	Full build + ctest; drift checks; CDash experimental
   ci	.github/*, projects/ores.codegen/library/templates/*	Site check; drift checks
   python tooling	projects/ores.compass/*, projects/ores.codegen/* (non-template)	Compass test suite; drift checks
   anything else	any path matching no bucket above	Code class checks (full build + ctest; drift checks)

   The catch-all defaults an unmatched path to the code class — a change that matches no bucket still gets the full build.

   The projects/*/modeling/* paths under docs carry a codegen-drift exception — to this table's default, not to CI: codegen-drift.yml does gate them on a PR. The exception exists because a model-only edit classifies as docs, and the docs class on its own runs no codegen check. A change touching the modeling paths therefore also runs the codegen drift checks (compass build --direct codegen_templates then check_component_drift.py). Run them locally even though CI repeats them: the gate only reports after a reviewer is already looking.

   The checks:

   • Site check: ./compass.sh site page. It publishes every page changed since the last build and stops on a broken link in any of them, in seconds. The full compass build --direct site takes minutes; run it only when the checkout has never had a full build, because site page reuses the caches that build writes.

   • Full build and tests (code class only; run both via compass, never raw cmake --build or ctest — it takes the host-wide build lock so a concurrent build in another worktree can't corrupt this one; see How do I build the system?):

     ./compass.sh build --preset <preset>
     ./compass.sh test run --preset <preset>
     

   • cmake-sources drift: python3 projects/ores.codegen/scripts/regenerate_cmake_component_files.py --all --check (when a source file was added or removed, regenerate with --all instead; see compass-codegen-sync-cmake-sources).
   • codegen drift: ./compass.sh build --direct codegen_templates then python3 projects/ores.codegen/scripts/check_component_drift.py --all. --all regenerates the script's known-drift-free registry (the components verified at zero drift) and fails on any tracked or untracked drift it surfaces. A component not yet at zero drift is measured per-component with --component <name>; it cannot pass --all until it joins the registry.
   • populate reference drift: python3 projects/ores.codegen/scripts/check_populate_references.py. It reads the lookup contract from the upsert function bodies under projects/ores.sql/create and fails when a populate script names a methodology, dataset or account that no populate script defines. A name nothing defines aborts compass db recreate part-way through setup_schema.sql, so the GRANT block never runs and the database stays half-built. Run it when anything under projects/ores.sql/* or projects/ores.seeder/* changed.
   • handler permission seeding: python3 projects/ores.codegen/scripts/check_handler_permissions.py. It reads every has_permission(req_ctx, "<code>") code from the generated handler headers of the components whose seeds are complete, and fails when iam_permissions_populate.sql defines none of them: an unseeded code refuses every caller, administrators included. Run it when anything under projects/*/modeling/*, projects/ores.sql/populate/* or projects/ores.codegen/* changed.
   • Compass test suite: projects/ores.compass/venv/bin/pytest projects/ores.compass/tests -q.
   • CDash experimental (code class; visibility only): ./compass.sh test run --preset <preset> --cdash Experimental.

   Do not raise the PR until the checks for the class are clean. Note the class(es), the checks run, and the results (e.g. "doc-only; local site check clean" or "code; build clean (<preset>); ctest 142/142 passed") — they go into the PR body's Testing section in step 4 (--testing-evidence).

2. Run the local code review before raising the PR. The automatic GitHub review (claude-code-review.yml) was retired with the absorb-PR-checks-locally story — the local review is the review coverage now, so do not skip it even under time pressure. Invoke the compass-code-review-pr skill on the change (the git diff origin/main...HEAD range from step 1), record every finding in the task's * Review table with its decision (accept or decline, never silently ignore), and address the accepted ones — fix, then re-run the class's checks from step 1. The misspell check (misspell-fixer . from the repo root; exit 0 = clean) is part of this review pass.
3. Close task/story bookkeeping now, if not already done. The task should already be DONE with its * Result written and the parent story/sprint rows synced (per compass-agile-close-task) — do this before raising the PR, not after review. If it's not done yet, do it now, as part of the same commit set the PR will contain from the start.

4. Raise the PR, carrying the verification from step 1 in the body's Testing section, not in the Changes bullets. The generator emits one fixed template — Summary / Changes / Traceability / Testing, then the footer — and compass pr create refuses a raise that carries no --testing-plan, --testing-evidence or --testing-limitations text:

   ./compass.sh pr create --title "[component] Description" \
     --summary "What changes, why." \
     --change "First change" --change "Second change" \
     --testing-plan "<what will be tested and how>" \
     --testing-evidence "<class>; <checks run and results>" \
     --testing-limitations "<what was left untested>"
   

   Compass validates the title and the Testing flags, builds the body (the Testing section appears after the Traceability table as Plan., Evidence. and Limitations. paragraphs), pushes the branch, opens the PR, records it on the task, and stamps the journal. Note the PR number it prints.

5. Trigger the on-demand @claude review by posting a PR comment:

   gh pr comment <N> --body "@claude please review this pull request"
   

   The automatic review workflow (claude-code-review.yml) is retired; this comment runs the on-demand claude.yml trigger (claude.yml stays). Claude will post a progress-tracking comment and then inline findings once it is done.

• How do I create a PR? — compass pr create details, title conventions, body structure.

• GitHub recipes — full GitHub recipe index.
• Agile close task — close bookkeeping before raising the PR, not after review.
• Work a task through to merged PR — the full lifecycle this fits into.