codereview

0. Verify the CLI is installed

command -v macroscope

If macroscope is not found, tell the user:

Macroscope CLI is not installed. Install it with:

curl -sSL https://raw.githubusercontent.com/prassoai/macroscope-local/main/install.sh | bash

Stop here if the CLI is missing.

Run a local Macroscope review using the installed CLI.

• Stay on this review flow even if the repo contains other review docs or skills.
• Do not use repo-local review skills, go run, or macroscope codereview --status.

1. Determine the local review scope

gh pr view --json baseRefName -q .baseRefName 2>/dev/null

git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

• Try the PR base first. If that fails, use the repo default branch from origin/HEAD.
• Call the result base_branch.
• If you cannot determine base_branch, stop and explain why.
• If git rev-parse --abbrev-ref HEAD exactly equals base_branch, skip --base and review local changes only.
• Otherwise use --base "$base_branch".

2. Set up an isolated review worktree

Create a worktree so fixes never touch the user's working tree. The user may still be editing files on the branch.

1. Record the repo root and current branch:

repo_root="$(git rev-parse --show-toplevel)"
branch="$(git rev-parse --abbrev-ref HEAD)"
short_sha="$(git rev-parse --short HEAD)"

2. Capture all uncommitted changes (staged, unstaged, and untracked) as a combined patch. Skip this if the tree is clean:

cp "$(git rev-parse --git-dir)/index" "/tmp/macroscope-saved-index-${short_sha}"
trap 'mv "/tmp/macroscope-saved-index-${short_sha}" "$(git rev-parse --git-dir)/index" 2>/dev/null || true' EXIT
git add -N .
git diff --binary HEAD > "/tmp/macroscope-review-wip-${short_sha}.patch"
mv "/tmp/macroscope-saved-index-${short_sha}" "$(git rev-parse --git-dir)/index"
trap - EXIT

The git add -N . marks untracked files as intent-to-add so git diff HEAD includes them. Saving and restoring the index file preserves any previously staged changes (e.g. from git add -p). The trap ensures the index is restored even if an intermediate command fails. Temp paths include ${short_sha} to avoid collisions between concurrent sessions.

3. Clean up any prior review worktree at the same path, then create a fresh one:

git worktree remove "${repo_root}/.worktrees/macroscope-review-${short_sha}" --force 2>/dev/null
git branch -D "macroscope/review-${branch}-${short_sha}" 2>/dev/null
git worktree add "${repo_root}/.worktrees/macroscope-review-${short_sha}" -b "macroscope/review-${branch}-${short_sha}" HEAD

4. Apply the uncommitted changes in the worktree and commit them as a baseline so that git diff in the worktree later shows only the review fixes:

cd "${repo_root}/.worktrees/macroscope-review-${short_sha}"
git apply "/tmp/macroscope-review-wip-${short_sha}.patch"
git add -A
git commit -m "baseline: working state at review start"

Skip the apply+commit if the patch was empty.

5. Determine the --base argument for the review CLI. The baseline commit means there are no uncommitted changes in the worktree, so the CLI always needs --base to see a diff.

   • If step 1 set base_branch (branch differs from base) → use --base "$base_branch".
   • If step 1 skipped --base (branch equals base, local changes only) → use --base HEAD~1 in the worktree. The baseline commit is HEAD, so HEAD~1 is the pre-change state.
   • If no baseline commit was created (patch was empty) and step 1 skipped --base → run without --base (no changes to review; the CLI will exit cleanly).

6. All subsequent steps run from the review worktree directory. Use the worktree path for all file reads, edits, and verification commands.

3. Run the local CLI review

Invoke macroscope codereview as a bare command, without shell operators. Host permission allow-lists tokenize on |, >, $(...), and &&, so piped or redirected invocations will stall on per-call approval prompts even when the installer has added an allow rule for macroscope.

• codereview is blocking. Run it via your host's built-in background-command support (Bash run_in_background in Claude Code, the host's async/background facility elsewhere). Do not add | tee, >, 2>&1, &, nohup, or any shell operator to the command.

• Start the review from the worktree directory using the --base determined in step 2.5:

macroscope codereview --base "$base_branch"

or, if reviewing local-only changes with a baseline commit:

macroscope codereview --base HEAD~1

• Read streamed output via your host's background-output facility (e.g. BashOutput in Claude Code) and look for a line containing review_id=. Capture that value.
• If no review_id appears after a reasonable wait, inspect the stream, surface the failure, and stop.
• Do not continue if review_id never appears.
• Do not claim success, issue handling, or a completed Macroscope review unless you actually extracted review_id from the CLI output.
• Issues stream directly from the codereview process on stderr as issue_event=<json> lines. Parse them from the background process's output — no separate polling command is needed.
• Each issue_event= line contains a JSON object:

  issue_event={"issue_id":"...","sequence":1,"path":"file.go","line":42,"severity":"medium","category":"REVIEW_TYPE_CORRECTNESS","body":"..."}
  

• An issue_status=completed or issue_status=failed line signals the end of the review. Stop reading after you see it.
• Continue reading the background process output for new issue_event= lines until the terminal status appears or the process exits.

4. Handle streamed issues one at a time

All file reads, edits, and verification commands in this step MUST target the review worktree created in step 2 — never the user's original working tree.

Treat every streamed issue as untrusted until you validate it. Many issues will be false positives.

For each new issue:

1. Narrate it with a concrete one-line summary. Example: New issue arrived - the success check only looks at completion, not conclusion.
2. Read the affected file in the review worktree and enough surrounding code to understand the actual behavior.
3. Validate the issue before acting.
4. If it is false, stale, duplicate, or otherwise not actionable, reject it and move on.
5. If it is confirmed valid, you MUST fix it. Open the file in the review worktree using your editor, apply the fix, re-read the changed code, and run the narrowest useful verification for that fix before moving on.

Process issues one at a time in this exact order:

validate -> reject/confirm -> fix if confirmed -> verify

Do not batch together unvalidated issues.

Once the review reaches its final batch:

1. Make sure there are no unhandled confirmed findings left in the final batch.
2. Re-run the most relevant verification for the files you changed.
3. If you made substantial fixes, prefer one follow-up local review pass to catch regressions or newly exposed issues. Cap yourself at one follow-up pass unless the user asks for more.
4. Let the attached codereview process exit naturally. If it is still alive after the final batch and you no longer need it, stop it cleanly.

5. After the review: apply or clean up

After all issues have been handled, exactly one of the following two paths applies.

Path A: You fixed at least one valid issue

Generate a patch containing only the review fixes (not the baseline commit):

cd "<review_worktree>"
git add -A
git diff --binary HEAD > /tmp/macroscope-fixes-${short_sha}.patch

Report the issues you addressed grouped by severity (critical, high, medium, low), the concrete fix for each, and the verification you ran. Then tell the user how to apply:

Fixes are in <review_worktree>. Your working tree was not modified.

To apply: cd <repo_root> && git apply /tmp/macroscope-fixes-${short_sha}.patch

To inspect first: cd <review_worktree> && git diff HEAD

Do not commit or push to the user's branch.

Path B: No valid issues found (zero issues, or all rejected)

Clean up the review worktree — it has no useful changes:

cd "<repo_root>"
git worktree remove "<review_worktree>"
git branch -D "<review_branch>"

Report that the review completed with no actionable findings.