Review Implementation

Review Implementation

Use this skill to verify and review repository changes before they are described as complete. Discover the project's own checks from its manifests, scripts, docs, CI config, and conversation context instead of assuming a specific package manager, framework, or command shape.

Workflow

1. Build context

   • Read repository instructions such as AGENTS.md, README, docs linked from those files, and relevant area-specific guidance.
   • Resolve the intended base from explicit user or downstream-workflow context, an existing PR base, an explicitly established parent integration branch, or the repository's discovered default branch for ordinary work. Do not hardcode a base branch or guess when these signals conflict.
   • Ensure the base ref is available and sufficiently current to support the review. If the intended base cannot be resolved or inspected, mark the review blocked.
   • Inspect the complete committed branch diff against the intended base using merge-base semantics, such as <base>...HEAD.
   • Inspect local changes in addition to the committed branch diff: staged, unstaged, and untracked files. Do not rely on a working-tree-only diff because it omits committed implementation work.
   • Inspect the commit list and diff statistics for the same range to detect unexpected scope or missing changes.
   • Inspect changed files directly when the diff alone is not enough to understand behavior.
   • If the touched area has a matching local skill or project rule, use it before judging that area.

2. Discover verification commands

   • Look for available commands in project manifests and task files such as package.json, lockfiles, workspace files, Makefiles, task runners, language-specific config, CI workflows, and repository docs.
   • Prefer commands that the repository already defines for linting, typechecking, tests, builds, formatting checks, generated-code checks, migrations, or framework validation.
   • For JavaScript and TypeScript projects, infer the package manager from lockfiles and scripts before choosing how to run a script.
   • Use explicit user instructions when they narrow the verification scope or name the expected checks.
   • If several reasonable commands exist, prefer the smallest set that covers lint/static analysis, type or compile checks, and tests for the changed behavior.
   • Do not invent commands. If a category has no discoverable command, report it as unavailable or not run with the evidence used to decide.

3. Run required verification

   • Run full-project checks by default when they are discoverable and practical.
   • Use scoped checks when the user requests scoped verification, the change is narrow and the repository supports scoped checks, or a full check is clearly impractical in the current environment. State the scope plainly.
   • Treat failing lint/static analysis, type/compile, test, or required build commands as blocking for workflows that need a completion signal.
   • If a command is unavailable, blocked by the environment, or requires approval that is not granted, report it as a verification gap instead of marking it passed.
   • If a command fails, capture the command, summarize the relevant failure output, infer the likely root cause, and suggest the shortest fix path.

4. Review the implementation

   • Review for behavioral bugs, regressions, accessibility issues, data-shape mismatches, routing or integration mistakes, security/privacy risks, generated-file misuse, and missing or incorrect tests.
   • Check whether test changes cover behavior and contracts, not only implementation details.
   • For UI changes, consider responsive layout, user-visible copy, interaction states, accessibility, and consistency with existing design patterns.
   • For data, schema, migration, or backend changes, confirm generated artifacts, migration safety, validation, and integration boundaries according to the repository's rules.
   • Keep the review focused on the requested change and directly related risks. Avoid unrelated refactors unless unrelated code creates a direct risk for the touched behavior.

5. Report results

   • Put review findings first, ordered by severity, with file and line references.
   • If there are no findings, say that explicitly and mention residual risks or verification gaps.
   • Include verification results with the exact commands that were discovered and run.
   • State the reviewed head, intended base, committed comparison range, and whether local changes were included.
   • For downstream workflows, provide a compact status summary that can be reused in issue comments, PR notes, or handoffs.

Output Format

Use this shape unless the user asked for a narrower result.

## Review Scope

- Head: `<branch or commit>`
- Intended base: `<branch or commit>`
- Committed range: `<base>...HEAD`
- Local changes: included/none/blocked

## Findings

- [P1] Short finding title - `path/to/file.ext:12`
  One concise explanation of the risk and what should change.

## Verification

- [x] `<command that passed>`
- [ ] `<command not run>` - reason
- [x] `<another command that passed>`

## Result

Verification status: pass/fail/blocked
Review status: pass/findings/blocked

Omit Findings only when the user asked for verification-only output. When all checks pass and no findings are found, write No findings found. instead of leaving the section empty.

Failure Handling

When a required verification fails, stop after reporting the failure unless the user explicitly asks to continue reviewing anyway. Use this structure:

Verification status: fail
Failed command: `<command>`
Likely root cause: <short explanation>
Fix path: <short next step>

When a required verification is blocked, unavailable, or not discoverable, use:

Verification status: blocked
Blocked or missing check: <check category or command>
Reason: <environment, approval, missing-script, or discovery reason>
Next step: <short next step>

Use the same blocked result when the intended base or complete branch diff cannot be resolved reliably.

Downstream Use

• Other workflows may use this skill as a verification gate.
• If a downstream workflow needs a completion signal, continue only when verification status is pass.
• Treat review findings as blockers when they show the implementation is incomplete, unsafe, or behaviorally wrong. Record nonblocking findings as review notes when appropriate.