Skip to content

Latest commit

 

History

History
111 lines (71 loc) · 13.5 KB

File metadata and controls

111 lines (71 loc) · 13.5 KB

Phase 1: Prep (review + verify + simplify)

Pre-PR quality phase: review, verify, and simplify changes before creating the PR.

1.1 Detect changed files and classify them

git diff --cached --name-only && git diff --name-only && git ls-files --others --exclude-standard
git diff --name-status "<remote>/<default-branch>"...HEAD

Classify the branch's changed files by the table below and run the steps each class owes.

Class Which files What it owes Where it runs
code source files (.sh, .bash, .py, .mjs, .js, .cjs, .ts, .ps1, .cs, project files) one fresh-context review (review:quality-gate under 50 changed lines, review:fanout above) unless the CI code-review lane covers it (review-venue.md), then simplify, then the comment pass (code-tidying:remove-comments), then verification:confirm §1.2 to §1.5
markdown .md files ai-slop:audit and docs-hygiene:audit-noise over the changed .md files §1.2.1
renames any R line in the name-status output a docs-hygiene:rename-references audit §1.2.1
skills plugins/*/skills/**, plugins/*/agents/** skill-quality:check over each changed skill §1.2.1
rules .claude/rules/** instruction-placement:check §1.2.1
tests test files the branch added or changed the testing:audit judge pass over them §1.2.1
security any diff that is not docs-only, as ready-for-review.md defines it (a diff touching an instruction surface is not) review:security-review over the pull request's diff ready-for-review.md §2.5.3

Check whether the branch holds more than one change. While classifying, ask whether the diff breaks into parts that do not need each other: no part reads a file, symbol or behavior another part adds, and each could be reviewed, reverted and released alone. A dependency upgrade, a parser bug fix and a new CLI flag on one branch are three such parts. When the diff breaks apart this way, name the parts and the files in each, propose one pull request per part, and ask before going on; narrow pull requests are easier to read and revert than one that mixes them. This is advice, not a gate: the user may keep one pull request. In a run with no one to ask, put the proposed split in the 1.6 report and continue with one pull request.

The order of the steps is not this file's to set. It is the fleet's pre-PR order, owned by docs/contracts/pre-pr-ordering/README.md. Read it there; this file cites it, never restates it.

Every skill named below is invoked through the Skill tool when its plugin is enabled, and replaced by the inline fallback stated beside it when it is not. Report each fallback and what it covered.

No code class? Skip 1.2 to 1.4; the verify gate (1.5) reduces to lint. The other classes still owe their audits: a docs-only branch owes the prose audits in 1.2.1. Satisfy any extra prep requirements (hooks, gates) the consuming project layers on PR creation, per its own docs.

1.2 Review the changes (the code class)

Read the review venue first (review-venue.md). When its code-review line reads ci, the CI code-review lane reviews the pull request once it is ready: skip this review (the 1.2.1 audits still run) and report the skip with the line's detail. When it reads local, or the read fails, run the review below and report it as the CI lane's stand-in, except under review_venue: ci, which skips it whatever the read returns. The review_venue setting decides what reads ci or local, and the report line under it. prep review-only follows the same rule.

Run one fresh-context review over the branch diff: /review:quality-gate under 50 changed lines, /review:fanout above it, when the review plugin is enabled.

  • Without that plugin: review the diff inline for correctness, error handling, security-sensitive surfaces, test coverage for new logic, and convention adherence against the project's own rules. Review agents (code-reviewer, security-reviewer, architecture-reviewer) serve the same purpose when your environment ships them
  • Auto-scale aspects to the diff: always check code errors; add test-focused review when test files changed; add type-design review for new type-heavy files. Collect findings

1.2.1 The other classes' audits

Run the audit each detected class owes, over the changed files of that class only.

Read which audit each class runs. The prep_audits list in docs/conventions/source-control.yaml can turn a class's audit off or replace it with a skill the repository names (config-resolution.md). Read it at the default branch, never the working tree:

git show "refs/remotes/<remote>/<default-branch>:docs/conventions/source-control.yaml" |
  bash "<skill-dir>/scripts/read-prep-audits.sh" --base <base-branch> --default-branch <default-branch> -

Each class line reads default (run the audit below), off (run none), or replace <skill> (invoke that skill through the Skill tool with the class's changed files as its arguments, in place of the audit below; for renames, each renamed file's old and new path). When the named skill is not available in this session, run the default audit and report why. Put one line per detected class in the 1.6 report: the audit that ran, off by prep_audits at <default-branch>, or the replacement. A fail-closed source line runs every default audit; report its reason. The comment pass (1.4) and security are not in the list and always run as written.

  • markdown: /ai-slop:audit when the ai-slop plugin is enabled, otherwise read the changed markdown against the project's own prose rules; and /docs-hygiene:audit-noise when the docs-hygiene plugin is enabled, otherwise read it for stale citations, dead references, and conversational residue
  • renames: /docs-hygiene:rename-references audit when docs-hygiene is enabled, otherwise grep the old path and the old name for every surviving reference. The class fires only when the diff reports a rename
  • skills: /skill-quality:check when the skill-quality plugin is enabled, otherwise run the project's own skill lint, or read each changed skill's frontmatter against the contract the project documents
  • rules: /instruction-placement:check when the instruction-placement plugin is enabled, otherwise confirm each changed rule's paths: glob still matches a tracked file
  • tests: /testing:audit --judge <remote>/<base-branch> when the testing plugin is enabled; it asks a separate model where each changed test's expected value came from, and its FLAG verdicts are findings for 1.3. Otherwise put judge pass not run: testing plugin not installed or not enabled in the 1.6 report; there is no inline fallback, because the writer cannot judge its own tests
  • security: not here. It reviews the pull request's own diff, so it runs in the ready step

Added suppressions (any diff that is not docs-only by file type; the instruction-surface definition in ready-for-review.md does not widen it). When /code-metrics:audit-suppressions is among the available skills, run it in its change scope against the pull request's base (--base <remote>/<base-branch>), and list in the 1.6 report every suppression the change adds, with its file, line, rule ids and reason. The list is advisory: it never blocks pull request creation, and no suppression is removed or rewritten on its account without the user. When the skill is not available, or the scan exits non-zero, put suppression check not run: <reason> in the report (for example suppression check not run: /code-metrics:audit-suppressions is not available) and continue.

Pre-push warnings (every branch). Run bash "<skill-dir>/scripts/prep-warnings.sh" --base <remote>/<base-branch> and list each line it prints in the 1.6 report. A skill-cut line names an existing SKILL.md or agent body that loses lines while no file under its eval home is added or changed; /playbooks:skill-authoring ships such a cut only with eval evidence of no loss. A protected-path line names a path the unattended merge (/source-control:babysit-prs) holds for a person, or a plugin manifest it holds when an executable key or plugin entry changes. The list is advisory, never blocking pull request creation, since a person may make either change on purpose. When the script exits non-zero, put prep warnings not run: <reason> in the report and continue.

Audits that persist findings hand them to one /review:fanout fix pass when the review plugin is enabled, and are applied by hand otherwise. Either way each finding goes through 1.3 first.

1.3 Verify every finding

For each finding:

  1. Extract the specific claim (API, pattern, behavior assertion)
  2. Verify against official docs and actual source for the exact versions in use (dispatch parallel verification agents when your environment supports them, up to 3 at a time)
  3. Cross-reference against the project's own conventions/rules
  4. Classify: VERIFIED (evidence confirms), INCORRECT (evidence contradicts), UNCERTAIN (cannot confirm)

Drop INCORRECT findings entirely. Flag UNCERTAIN with a note.

Present the findings in a structured table, leading with the verified findings you would block the merge for, each with file:line, why it is wrong, and how to show it fails (a failing test, command, or input). The remaining verified and UNCERTAIN findings follow. Pause for user review and fixes.

1.4 Simplify, review, and verify

Unless quick or review-only scope:

  1. Run /simplify over the branch diff when that capability resolves in this session; otherwise do a manual pass for dead code, needless indirection, and duplication introduced by the branch
  2. Run the comment pass over the branch's changed code files, after simplify and before any review of the result: /code-tidying:remove-comments --pipeline --base <remote>/<base-branch> when the code-tidying plugin is enabled. Its default posture, necessary, deletes warnings about this repository's own code, a security warning included, and stages each in its report. An unattended run (invoked with --unattended, or no person drives it: a loop lane, a CI lane, a dontAsk session, a dispatched worker) applies no comment edit unless the consuming project's instructions pre-approve applied comment edits in unattended runs: without that, run /code-tidying:remove-comments report --pipeline --base <remote>/<base-branch> and put its proposals in the 1.6 report. Without the plugin, put comment pass not run: code-tidying plugin not enabled in the 1.6 report
  3. Show the simplify and comment-pass diff: run git diff and present what changed. Automated simplification fixes and comment deletions are not research-verified; treat them like any code-review finding: inspect each change, approve or revert
  4. Pause for user review: let the user approve/reject simplify and comment-pass changes before proceeding
  5. Re-run tests on approved changes
  6. Run the verify gate (1.5)

1.5 Verify gate (hard: blocks PR creation)

Run the project's full build + test + lint surface, via /verification:confirm when the verification plugin is enabled (or /toolchain:check for the mechanical half alone) and otherwise the ecosystem-native commands (dotnet build && dotnet test, npm test, pytest, shellcheck, markdownlint, …) for every ecosystem the branch touches. All results must be clean before proceeding to PR creation. A /verification:confirm NOT VERIFIED whose only cause is verification: skipped (<level>), from the default branch's level, counts as clean here (/verification:confirm's PR-prep gate rule).

Run the full cross-cutting surface, not just the "obvious" ecosystem. A branch that "looks dotnet-only" can still break CI through a touched README, an unmarked .sh script, or a modified workflow file. Mirror locally whatever CI will run. The project's CI workflows are the canonical list of what must pass.

Decision rule:

  • Any FAIL → stop. Address each before reattempting. Do not proceed to PR creation
  • Any skip due to "tool missing" → install the tool or document why the skip is acceptable in this PR (rare, since it is almost always faster to install)
  • All clean (or only non-applicable skips like "no .md changes") → proceed to PR creation

This gate runs last, so nothing that edits the tree may run after it.

Why this gate is hard: cost asymmetry. A mechanical issue caught locally costs seconds; in CI it costs a multi-minute round trip plus rebase/repush overhead, and one sloppy PR can waste half a dozen CI cycles on issues all catchable locally.

1.6 Report

Report: the review venue's code-review line and whether the 1.2 review ran or was skipped for it, findings verified/dropped, simplify ran/skipped, the comment pass applied, report-only or not run (with its proposals when report-only), verify gate pass/fail per ecosystem, which classes 1.1 detected, the pre-push warnings from 1.2.1, and any split 1.1 proposed with the user's answer. Proceed to PR creation.

Prep before create is the developer loop. The branch updates in create.md §2.2 and ready-for-review.md §2.5.2 both move HEAD after prep, so the ready step re-runs the verify gate on the head it flips.