Review fix ship

Review Fix Ship

Use a review-first workflow with explicit approval gates. Keep repository mutations separate from analysis. Never invent findings to reach five items.

This Agent Skill supports Codex and GitHub Copilot. Read hosts.md when installing, publishing, or troubleshooting host discovery.

Quick Start

1. Locate this skill directory and set the helper path. Commands below work on macOS, Linux, and Windows with Node.js >= 18.

   macOS or Linux:

   reviewctl="<skill-dir>/scripts/reviewctl.mjs"
   

   Windows PowerShell:

   $reviewctl = "<skill-dir>\scripts\reviewctl.mjs"
   

2. Inspect the repository before analysis:

   node "$reviewctl" preflight --repo <repo>
   node "$reviewctl" tools doctor --repo <repo> [--provider <github|gitlab|all>]
   node "$reviewctl" review start --repo <repo> --scope <scope> [--scope <scope> ...]
   

3. Treat review start as the default exploration gate. It normalizes scope, snapshots detected tools, activates the token-efficiency policy, and reports CodeGraph readiness before code exploration begins. Default to caveman lite and explicit rtk wrappers when detected. Read token-efficiency.md before exploration and platforms.md when shell or OS differences matter.

4. Use the returned runId for all later commands. Read review-rubric.md before producing findings and output-contracts.md before recording them.

5. Initialize the ignored repository-local artifact mirror, record verified findings, and ask the user which single ID to activate:

   node "$reviewctl" artifacts init preview --repo <repo> --run-id <run-id>
   node "$reviewctl" artifacts init run     --repo <repo> --run-id <run-id> --preview-token <token> --confirm
   node "$reviewctl" state record-findings --repo <repo> --run-id <run-id> --file <findings.json>
   node "$reviewctl" state activate --repo <repo> --run-id <run-id> --id <finding-id>
   

6. Ask whether to create a branch or worktree for the active finding. Always show workspace preview output before asking for approval and running workspace create --confirm.

Review Workflow

1. Normalize Scope

Bind one run to one repository. Accept multiple scopes and merge them into one review surface:

• branch names or commit-ish values
• base...head comparisons
• repository-relative directories or files
• GitHub PR URLs
• GitLab MR URLs, including self-hosted GitLab

Use scope normalize; do not hand-edit run state. Reject remote URLs that conflict with the repository origin when an origin exists. Treat directory and file scopes as filters over each diff target. When a repository path and revision have the same name, reject the ambiguous input and ask for ref:<value> or path:<value>. Keep unprefixed values for unambiguous scopes.

If a PR or MR URL is present, run tools doctor and use remote fetch to cache available remote metadata and patches. If the provider CLI is missing or unauthenticated, continue local analysis where possible and report the missing adapter. Read providers.md only when remote input or submission is involved.

2. Use Token-Efficient Tools

Treat caveman, rtk, and CodeGraph as optional accelerators. Run review start before code exploration so scope normalization and efficiency activation cannot be skipped accidentally. For recovery or debugging, tools policy, scope normalize, and efficiency activate remain available as separate commands. Use detected tools autonomously, but preserve the no-dependency fallback.

• Activate installed caveman in lite mode for progress and summaries. Keep findings, approval prompts, plans, warnings, diagnostics, commit messages, and PR/MR drafts complete.
• Prefer explicit rtk wrappers for high-volume exploratory shell output such as Git status, diffs, searches, file reads, file listings, lint, builds, tests, and manual provider reads.
• Record the first successful use of each rtk route and every native fallback with efficiency record. Keep reviewctl operations, provider calls made inside remote fetch, and Git writes raw.
• Prefer CodeGraph MCP tools for structural questions, call paths, and impact analysis when available. Use CodeGraph CLI as a fallback. Ask before running codegraph init -i because it creates .codegraph/ in the target repository.
• Never install or globally configure an accelerator without user approval.

Read token-efficiency.md for the decision table and fallbacks.

3. Find and Verify Issues

Review the normalized surface from five perspectives: correctness, security, reliability/performance, API/data-contract, and test gaps. Run independent passes in parallel when subagents are available. Otherwise perform focused sequential passes.

Run a verifier pass over every candidate. Keep only findings with concrete evidence, confidence >= 80, and a material impact. Return at most five findings globally across all requested scopes. Rank by severity, blast radius, reproducibility, and fix leverage. Do not include style-only comments or speculative concerns.

Present the findings in Chinese for user selection. Include the evidence location, trigger, impact, a concise scenario with observed and expected behavior, recommended fix, viable alternative, and validation approach.

4. Isolate Selected Work

Activate exactly one finding at a time. Preserve all reports so the user can finish or defer the active finding and activate another later. Ask the user to choose branch or worktree; do not apply a silent default.

Use:

node "$reviewctl" workspace preview --repo <repo> --run-id <run-id> --finding-id <id> --mode <branch|worktree> [--path <path>] [--start-ref <ref> --target-branch <branch>]
node "$reviewctl" workspace create  --repo <repo> --run-id <run-id> --finding-id <id> --mode <branch|worktree> [--path <path>] [--start-ref <ref> --target-branch <branch>] --preview-token <token> --confirm

Never force branch creation, reset state, delete worktrees, or clean user changes. For a single base...head comparison, create the repair workspace from head and target the later PR or MR at base. Require explicit --start-ref and --target-branch when the normalized scopes cannot determine both values safely. Each preview returns a one-time previewToken. Pass that token to the matching create or run command. Reject missing, stale, replayed, or parameter-mismatched tokens.

5. Write and Approve the Plan

Write a detailed action plan using plan render; include the finding evidence, example, implementation steps, expected files, tests, and completion criteria. The authoritative plan is saved outside the repository and mirrored under the ignored .review-fix-ship/ directory.

node "$reviewctl" plan render --repo <repo> --run-id <run-id> --finding-id <id> --title <title> --finding <text> --step <step> --test <test>
node "$reviewctl" state mark --repo <repo> --run-id <run-id> --finding-id <id> --to plan_approved

Show the rendered plan and wait for explicit user approval before marking plan_approved. Do not modify repository files before that mark succeeds.

6. Implement and Self-Review

Enter the active workspace, mark implementing, implement the approved plan, and run repository-native lint, tests, and build checks. Then inspect the complete diff for correctness, maintainability, security, regressions, and missing tests. Fix any issues and repeat checks.

Record a concise self-review file under the run directory, then advance:

node "$reviewctl" state mark --repo <repo> --run-id <run-id> --finding-id <id> --to implementing
node "$reviewctl" state mark --repo <repo> --run-id <run-id> --finding-id <id> --to self_reviewed --self-review-file <file>

Read workflow-state.md when recovering an interrupted run or troubleshooting a blocked transition. Use state status --latest, state finish, and state defer to resume or release the active finding without creating parallel repair work.

7. Prepare and Submit the Change Request

Render an English draft after self-review. Follow repository templates and title conventions when present. Otherwise use type(scope): concise summary and the bundled provider template.

node "$reviewctl" draft render --repo <repo> --run-id <run-id> --finding-id <id> --provider <github|gitlab> --title <title> --summary <summary> --change <change> --testing <test>

Require separate user approval before each mutation:

Stage only the intended files after implementation and self-review. Do not use an unscoped git add . when unrelated changes exist. Pass the intended repository-relative files to commit preview; commit run rejects staged files that do not exactly match that approved allowlist.

node "$reviewctl" commit preview --repo <repo> --run-id <run-id> --finding-id <id> --message <message> --file <path> [--file <path> ...]
node "$reviewctl" commit run     --repo <repo> --run-id <run-id> --finding-id <id> --message <message> --file <path> [--file <path> ...] --preview-token <token> --confirm
node "$reviewctl" push preview   --repo <repo> --run-id <run-id> --finding-id <id>
node "$reviewctl" push run       --repo <repo> --run-id <run-id> --finding-id <id> --preview-token <token> --confirm
node "$reviewctl" submit preview --repo <repo> --run-id <run-id> --finding-id <id> --provider <github|gitlab> --title <title> --body-file <file>
node "$reviewctl" submit run     --repo <repo> --run-id <run-id> --finding-id <id> --provider <github|gitlab> --title <title> --body-file <file> --preview-token <token> --confirm

Before previewing or running a push, require the checked-out HEAD to equal the commit recorded by commit run. If the branch changed, repeat self-review and commit approval before pushing.

Never call gh pr create --dry-run; it may still push. Never pass --fill, --push, or --yes to glab mr create. If gh or glab is missing, return the generated draft and explain the installation or authentication requirement. Do not install CLIs automatically.

Resources

• Read review-rubric.md for ranking and verification.
• Read workflow-state.md for states, guards, and recovery.
• Read providers.md for GitHub and GitLab behavior.
• Read platforms.md for macOS, Linux, and Windows requirements.
• Read hosts.md for Codex and GitHub Copilot installation paths.
• Read token-efficiency.md for optional caveman, rtk, and CodeGraph usage.
• Read output-contracts.md for persisted JSON and Markdown shapes.
• Run node scripts/reviewctl.mjs help for the deterministic helper interface.