# Review guidelines AI agents and human reviewers should follow this guide together with the [development flow](development-flow.md) and [PR template](../.github/pull_request_template.md). The default branch is `master`. Evaluate evidence for the current PR head rather than assuming a previous review or a checked box proves the current change works. ## Review the implementation and evidence The central review question is: **Does this PR completely solve the Issue, without unnecessary scope or complexity?** 1. Read the source Issue and PR description. Identify the problem, intended outcome, scope, pre-merge acceptance criteria, and any genuinely necessary post-merge verification. Do not invent routine human-only requirements. 2. Record the reviewed head commit and inspect the full diff. Check correctness, focused scope, regressions, compatibility, and unnecessary changes. For parser changes, inspect affected formats, decoding, coordinate conversion, public exports, and generated bundles as applicable. Check that documentation matches actual file names and commands. Review changes to user-facing commands, messages, examples, or interfaces against the [UI/UX principles](../Readme.md#uiux). 3. Evaluate applicable automated checks for that head and validation reported in the PR. Use the build/test commands and limitations in the development flow. Verify the evidence, including test output; distinguish passed, failed, skipped, and unperformed checks. A documentation-only change needs template, Markdown, link, and consistency checks, not new runtime tests or parser builds. If a check cannot run, assess its impact and whether other evidence is enough. Apply the [test and CI performance principles](development-flow.md#test-and-ci-performance-principles): ask what additional defect new coverage detects, whether existing checks duplicate that assurance, and what execution and maintenance cost it adds. Preserve required regressions and meaningful integration coverage. 4. Confirm the reviewed head merges cleanly into current `master` using current GitHub mergeability information or a local trial merge in a disposable worktree. Refresh unknown or stale mergeability before deciding. Report conflicts as actionable findings. Do not rely on mergeability for an older head or an outdated base. Before merge, recheck if the head or base changes. Check both directions against the source Issue: - **No missing work:** verify that every requirement the PR claims to resolve is implemented, behavior matches the Issue's expected outcome, and appropriate validation supports the result. Simplicity must not excuse omitted requirements, error handling, or necessary regression coverage. - **No unnecessary work:** check for unnecessary abstractions, speculative extensibility, unrelated refactoring, new frameworks or subsystems, and extra policies or configuration without a demonstrated need. An otherwise relevant parser fix can still be overengineered, for example by introducing a plugin framework for a single format correction. Added complexity is not automatically beneficial, especially in AI-generated changes. Prefer the smallest coherent change and design that fully satisfies the source Issue. Preserve appropriate existing architectural conventions; abstractions are appropriate when their complexity is necessary to solve the actual Issue. Require an explanation of that need when the justification is unclear. ## Classify findings and choose the outcome For each material finding, give its location, impact, and concrete resolution or verification. Distinguish these cases: - **Agent-fixable:** a code or documentation defect, concrete omission, unjustified scope or complexity, merge conflict, or missing applicable validation that an agent can address. Request focused fixes and review the updated PR again, including affected behavior and validation. - **Necessary external input:** an unresolved requirement, inaccessible evidence, or essential human/device/external confirmation. State the exact question or evidence needed and why it affects pre-merge acceptance. Pause the dependent decision while continuing unaffected review; do not repeatedly request code fixes for a condition that requires an external answer. - **Post-merge verification:** a necessary check possible only after merge. Record the plan and later result separately. A pending deployment, published-site, or release check does not block pre-merge approval or require a completed PR metadata field or checkbox. Approve when the implementation fully satisfies the Issue without unjustified scope or complexity and applicable pre-merge checks are sufficient. Request changes for material, agent-fixable blockers; explain any necessary external blocker without presenting it as a code defect. Optional improvements are suggestions, not new acceptance criteria. Report the reviewed head, evidence, findings, decision, and any required post-merge plan so the next workflow step can act on the result. ## Merge and closing references Before an authorized merge, confirm that approval and applicable repository checks still cover the current head and that it merges cleanly into current `master`. If the head changes, review the new diff and affected checks before merging. Do not merge based on stale approval or bypass repository requirements. ProjectWeave publication adds `Closes #N`; its merge/close nodes close the source Issue. Preserve this metadata for a complete implementation with applicable mandatory pre-merge checks satisfied. Do not request removal of `Closes #N`, require the Issue to stay open, or withhold approval solely because necessary post-merge verification is pending. Such requirements conflict with the existing flow and can create a `Review -> Fix -> Publish -> Review` loop. Pending post-merge-only verification does not make the implementation partial; actual missing work or mandatory pre-merge acceptance remains blocking. Intentional partial work must state remaining scope and must not automatically close its parent Issue. Follow the [Issue closure lifecycle](development-flow.md#review-merge-and-issue-closure): close the original Issue after successful merge, then record required post-merge evidence honestly and use new or existing linked Issues for discovered defects, without reopening the original solely for follow-up. When no post-merge verification is required, state `None`.