Code Review Tutorial

Prerequisites#

Before starting this tutorial, ensure:

1. uf init completed — your project has Divisor review agents deployed (.opencode/agents/divisor-*.md)
2. gh CLI installed and authenticated — /uf.review-pr uses gh to fetch PR metadata and CI results

which gh && gh auth status

If gh is not installed, get it from cli.github.com. If not authenticated, run gh auth login.

Step 1: Pre-PR Review with /uf.review-council#

Before you push your changes and create a PR, run /uf.review-council to catch issues locally:

/uf.review-council
/uf.review-council [N]        # optionally specify a PR number
/uf.review-council code [N]   # explicitly select code review mode

When a PR number is provided, the council posts its consolidated findings as a GitHub PR review after completing the local review. Without a PR number, the review runs locally only.

What Happens#

The review council runs in two phases:

Phase 1: CI Soft Gate — runs your project’s build, test, and lint commands (derived from .github/workflows/). When a check fails, the council determines whether the failure is new (introduced by your branch) or pre-existing (already broken on main). New failures block the review — no point reviewing code that introduces regressions. Pre-existing failures are reported as informational findings but do not block. The council checks the main baseline via the GitHub CI API first, falling back to a temporary git worktree if API data is unavailable.

Phase 2: Divisor Review — launches 5+ review personas in parallel, each with a different focus:

Expected Output#

Phase 1: CI Gate
  ✓ npm run build — passed (536ms)

Phase 2: Divisor Review
  Adversary:  APPROVE (0 findings)
  Architect:  APPROVE (1 LOW — weight inconsistency)
  Guard:      APPROVE (0 findings)
  Testing:    APPROVE (0 findings)
  SRE:        APPROVE (0 findings)
  Curator:    APPROVE (0 findings)

Council Verdict: APPROVE

If any persona returns REQUEST CHANGES, the council verdict is REQUEST CHANGES. Fix the findings and re-run. The review council iterates up to 3 times, auto-fixing LOW and MEDIUM findings where possible.

Gaze integration (optional): If Gaze is installed, the review council runs quality analysis (CRAP scores, test coverage) as Phase 1b. This is informational — it does not block the verdict.

Optional: Post to GitHub#

When a PR exists for your branch, /uf.review-council can post its consolidated findings as a GitHub PR review. The council detects an open PR automatically via gh pr view, or you can specify a PR number explicitly with /uf.review-council N.

How it works: After all personas complete their local review, the council aggregates their findings into a single GitHub review with per-persona sections. The council verdict maps to a GitHub review event:

Pre-posting safety checks:

• Duplicate detection — skips posting if the council has already posted an identical review on the same commit
• Stale review dismissal — warns if previous council reviews on older commits should be dismissed
• CODEOWNER warnings — alerts if the PR modifies files owned by teams not represented in the review

Before posting, the council asks for human confirmation. No review is posted without your explicit approval.

Graceful degradation: If gh is not installed, not authenticated, or no PR exists for the current branch, /uf.review-council runs the full local review without errors. GitHub posting is strictly optional — the local review workflow is unchanged.

Step 2: Push and Create a PR#

Once the review council approves, push your changes and create a PR:

/uf.finale

Or manually:

git push -u origin my-branch
gh pr create --title "feat: add user auth" --body "..."

Step 3: Post-PR Review with /uf.review-pr#

After the PR is created and CI has run, review the PR:

/uf.review-pr

This auto-detects the open PR for your current branch. To review a specific PR (including someone else’s):

/uf.review-pr 42

What Happens#

/uf.review-pr runs a structured review informed by CI results:

1. Resolve PR — auto-detect or use the provided PR number
2. Fetch metadata — title, description, changed files, branch info
3. CI check results — fetch pass/fail status for every check
4. Causality classification — for each failing check, determine if it is PR-caused or pre-existing
5. Local tool pre-flight — run tools only for checks CI did not already cover
6. Scoped diff — fetch the PR diff (skipping lock files, generated code, binaries)
7. Spec alignment — locate the associated spec for intent checking
8. AI review — judgment on alignment, security, and architecture
9. Structured report — severity-classified findings
10. Verdict posting — posts the verdict as a GitHub PR review for all outcomes (APPROVE, REQUEST_CHANGES, or COMMENT)

Expected Output#

PR #42: feat: add user auth
Branch: feature/user-auth → main
Files changed: 8 (+342, -12)

CI Checks:
  ✓ Build & Test — passed
  ✓ Lint — passed
  ✗ yamllint — FAILED (pre-existing)

Causality Analysis:
  yamllint: base branch FAIL, PR FAIL → Pre-existing
  (This failure exists independently of your PR)

Local Pre-flight:
  Skipped: build (CI passed), lint (CI passed)

Review Findings:
  [HIGH] Missing error handling in auth.go:42
  [MEDIUM] Consider extracting helper function at auth.go:87

Verdict: 2 findings (1 HIGH, 1 MEDIUM)

Step 4: Understanding CI Causality#

When CI checks fail on your PR, the key question is: did my changes cause this?

/uf.review-pr answers this by checking whether the same check also fails on the base branch:

PR-caused failures are reported as HIGH or CRITICAL findings. These are your regressions.

Pre-existing failures are reported separately and do not block the PR verdict. They are not your problem — but /uf.review-pr can help fix them.

Step 5: Fix Branches for Pre-existing Failures#

When pre-existing failures are found, /uf.review-pr offers to create a fix branch:

I identified 1 pre-existing CI failure:
  - yamllint: trailing whitespace in config/database.yml

Would you like me to create a fix branch?

If you agree, it creates fix/pr-42-yamllint from the base branch with a minimal fix. The branch stays local — you review and push when ready.

Safety guards:

• Will not create a fix branch if you have uncommitted changes (dirty-tree guard)
• Will not overwrite an existing branch with the same name (collision check)
• Will not attempt non-trivial fixes spanning more than 3 files

The Complete Loop#

The two review commands fit into the standard development workflow:

/speckit.specify          # define the work
       ↓
/uf.unleash               # implement autonomously
       ↓
/uf.review-council        # validate locally (pre-PR)
       ↓
/uf.finale                # commit, push, create PR
       ↓
/uf.review-pr             # review with CI data (post-PR)
       ↓
Merge                     # after reviewer approval

You can use either command independently — they do not depend on each other. But together they catch issues at two different points: before the code leaves your machine and after it runs through CI. Additionally, /uf.review-council N can optionally post its findings to an existing PR, bridging the pre-PR and post-PR stages when you want multi-persona review results visible on the PR itself.

Decision Table#

/uf.review-council N vs /uf.review-pr N: Both target a specific PR, but they serve different purposes. /uf.review-council N runs the full multi-persona local review and posts the aggregated findings to the PR. /uf.review-pr N fetches CI results, performs causality analysis (PR-caused vs pre-existing failures), and reviews the PR diff with that context. Use /uf.review-council N when you want the council’s multi-persona review visible on the PR; use /uf.review-pr N when you need CI-aware review with causality classification.

See Also#

• Common Workflows – /uf.review-council vs /uf.review-pr comparison table and full command reference
• Quick Start – Install and verify the toolchain
• Developer Guide – Daily workflow with the uf CLI