REVIEW_HELPER refers to oil-code-review the change-collection script review_helper.py bundled with the Skill; see that Skill for usage. If not installed, use git status and git diff --stat against the contract instead.
Core rules
- Grade by complexity; refuse to over-engineer small tasks: do not force a long plan document onto a clear two- or three-line change; choose the lightest alignment method by
L1 / L2 / L3. - Plan review is closed out within this stage: reviewing the plan is a built-in action of
oil-planand is not mixed intooil-code-review(the latter only reviews code that has already been written). - Must be written in language the user can understand: readers need not care about the underlying framework's internal implementation; after reading, they should clearly know "what changes externally, which parts are touched and what existing infrastructure is reused, what is out of scope this time, exception boundaries, and how to accept it." Reject jargon, empty slogans, and piling up large blocks of implementation code.
- Verify facts and clear disagreements before starting: no checkbox-style fake percentage scoring. Before starting, enforce only two real red lines: ① the existing file paths, reusable components, and test commands mentioned have been genuinely verified to exist in the repository; ② key disagreements affecting user experience or scope boundaries have been clarified with the user.
- Reproduce defects before fixing: at any level, reproduce the problem before fixing a defect (write a failing test first if possible, and confirm it truly fails); after the fix, accept it by turning the same case green.
- The dispatch contract locks down direction and test rhythm: when handing off to an external execution Agent (e.g., via
oil-delegate) or implementing in the current session yourself, write down the direction, mandatory reusable components, files allowed to be modified, andtest fast rulesall at once, to prevent the executor from diverging on its own or repeatedly running empty tests every couple of lines changed.
First grade by complexity (L1 / L2 / L3)
| Level | Applicable scenarios | Execution method | Default stopping point |
|---|---|---|---|
| L1 Lightweight direct | Clear single-module patch, copy change, style tweak, small defect with a clear location | 2–3 sentences explaining the fix (reproduce defect first) → modify directly or dispatch → run one related local fast test | Complete modification and fast-test feedback |
| L2 Conversational plan | Routine single-feature development, medium refactor, or 1–2 product trade-offs | Verify code facts → give a concise four-element plan and items awaiting decision in the conversation → implement after user approval | User confirms plan (or proceeds to dispatch implementation) |
| L3 Milestone spec | Cross-subsystem refactor, new data format/build pipeline, or high-risk architecture change | Verify facts → write into docs/ spec document following the project's existing style → independent critical self-review → dispatch in batches or by Worktree after user confirmation |
Spec finalized and approved, ready to enter dispatch |
| Review an existing plan | The user provides a ready-made plan and asks whether it is reliable or has any gaps | Compare against the real code in the workspace and AGENTS.md / DESIGN.md to identify factual conflicts, unused existing infrastructure, and boundary loopholes |
Output a list of issues and revision suggestions |
Mid-way escalation: if during execution it is discovered that high-risk modules need to be touched (concurrency and background tasks, data storage formats and migrations, irreversible operations such as file deletion, security-sensitive logic such as authentication/authorization/payment, external APIs and data contracts, packaging, release, and upgrades, as well as directories marked as high-risk in the development conventions), the changes exceed the originally planned files, or new product trade-offs emerge, stop and escalate to L2 / L3 to realign, rather than forcing it through to completion.L1 As long as a change touches high-risk modules, it is still handed to oil-code-review for review.
Workflow
1. Pre-check of code facts and conventions
- Check whether the current session already has the real paths of the target modules, reusable public components/shared modules, and the project-specified local quick-test commands; if not yet clear, first verify them read-only according to
oil-explore; strictly do not fabricate paths from guesswork. - If the repository has
AGENTS.mdorDESIGN.md, first check the hard constraints on architectural layering, design tokens, test isolation, and packaging and distribution. - If
AGENTS.mdhas a development conventions subsection whose title containsoil-dev: write the quick-test and gate commands directly into the verification standards and contract, write the do-not-modify directories into the contract's do-not-modify scope, and when changes involve high-risk directories, handle them according to the mid-way escalation rule and arrange a review. When this section is absent, judge according to the default high-risk list above, and you may suggest usingoil-governto add it.
2. Explain the plan in plain language (L2 / L3)
Refer to plan readability standards and dispatch template, and write it clearly around the four core questions (if written to disk in docs/, follow the target repository's original heading style; do not force fixed template wording):
- What to solve and externally visible changes: compare specifically how the operations, interface, or input/output that users see change before and after the change.
- Scope of changes and reuse of existing infrastructure: state clearly which set of public components, shared types, or functions from the repository are directly reused, which files are changed (written as paths or wildcards, to be used directly for comparison during later review), why new files are created, and explicitly listnot done in this phaseboundaries.
- Key trade-offs and exception, security, compatibility, and packaging boundaries: when there are multiple approaches, explain the pros and cons and the recommendation in everyday language; explain empty states, mid-way cancellation, permission checks and external input handling, whether old data can be read and how it is migrated, whether external interfaces remain compatible, and the formal packaging and runtime boundaries after leaving the development directory (such as resource loading, permissions, and conditional compilation).
- Layered verification standards: distinguish between the “local quick-test commands run by the executor after changes” and the “full/end-to-end/packaging gates run once uniformly before merging”.
3. Internal review of the plan and confirmation of key questions
- Self-check and independent fault-finding: verify one by one that the file paths cited in the plan actually exist in the repository; if it is
L3a cross-module high-risk plan and the environment already hasoil-delegateinstalled, an independent model accustomed to rigorous defense can be asked to find concurrency, state transition, and packaging blind spots, and the valid hard risks can be added to the plan. When delegating, use--role critique: it selects an Agent based on the user's saved preferences and automatically runs in read-only mode; returnsUSE_HOST, switch to a fresh read-only sub-Agent of the current Agent, returnsNEEDS_ROLE_CHOICE, ask the user once and follow the instructions inoil-delegateto save. After returning, confirm thatgit statushas not changed. - Confirm key decisions with the user: on the first submission of the
L2 / L3plan, use a few clear and direct sentences to point out the most core approach and 1–2 pending decision multiple-choice questions, and only start after confirming the user truly understands and approves what will be done next. If there are no open questions and the user's team has agreed to proceed with low friction, state the chosen default plan and execute directly.
4. Strict contract dispatch and parallel isolation
After the plan is confirmed, proceed to implementation:
- Protect the workspace first: before dispatching in write mode, confirm the workspace is clean (
git statushas no uncommitted changes), or execute in an independent Worktree instead. When the user has uncommitted changes, first ask clearly whether to commit, stash, or open a separate Worktree, so that the executor's changes are not mixed with the user's. - Dispatch by contract: follow strict dispatch contract and execution fast rules to assemble the prompt, and write the mandatory reusable infrastructure, files allowed to be modified, prohibited modification scope, andtest frequency control disciplineinto the contract. When dispatching via
oil-delegate, use--role implement, and select the execution Agent according to the user's preferences; whenUSE_HOSTis returned, the current session implements it itself. When the current session implements it itself, it also follows these fast rules. - Multi-task parallel Worktree isolation: if advancing multiple mutually independent tasks at the same time, first confirm that the hot files modified by each task do not overlap, place each into an independent Git Worktree under the same-level parent directory (do not nest child Worktrees inside the main repository directory), and record the branch name and Worktree path of each task for final merging; in native projects with heavy compilation caches, you can first use copy-on-write (such as macOS APFS
cp -cR) to clone the main repository build directory to avoid cold-compilation waiting. - Accept execution results, not just self-reports: first use
REVIEW_HELPER --allow <契约里允许的路径>to check for out-of-scope changes, then check whether tests have been deleted, skipped, or weakened, and then personally run the local quick tests in the contract once (seconds-level, used to verify the results); slow tests are not rerun at this step. When the executor says "the baseline was already failing," run the same command on the main branch to verify.
5. Final merge
After review passes (or L1 quick tests pass), follow the final merge checklist to complete the last step: run a merge gate once on the branch to be merged; if the gate fails, first determine whether it was introduced by this change; commit the merge according to repository conventions (the executor does not commit on its own); merge multiple Worktrees one by one in dependency order, and run the gate once more after all are merged; finally clean up the merged Worktrees and handle the retention of L3 specification documents.
Output and follow-up handoff
In the planning phase, output the refined plan and pending decision questions, then stop; after dispatch implementation is complete, deliver the change summary and local quick test results; in the final phase, deliver the gate results and merge status.
| Downstream intent | Handoff action |
|---|---|
| Independently review high-risk or core product code | Enter oil-code-review, and hand over the paths allowed to be modified in the contract for it to compare |
| When writing a plan, you find that the underlying call chain of a certain block has not yet been fully understood | First use oil-explore to locally verify the code anchor points |
| Clean up parallel Worktrees after merging | Enter oil-govern to take stock of Worktrees, and clean up only the ones confirmed safe to clean |
Resource Navigation
- references/plan-rubric.md: Read when drafting or reviewing a plan, assembling an external execution contract, or wrapping up and merging; includes a comparison of good and bad plans, a pre-action checklist, a quick-rule dispatch template, and a wrap-up and merge checklist.