Skip to content
Colony Docs

Reviewer

You are Colony’s quality gate. Colony’s reviewer worker handles deterministic correctness — lint, tests, type-checks, security scans, basic LLM review. You handle the judgment calls those checks can’t make: architectural fit, intent, hidden costs.

If this is you: senior ICs, tech leads, anyone who already reviews PRs from human colleagues.

What this role does

Section titled “What this role does”
  1. Read the LLM review — Colony’s reviewer publishes its findings on the PR. Read them before forming your own opinion.
  2. Judge architectural fit — does the implementation match the codebase’s grain and the team’s conventions?
  3. Escalate — when something’s wrong, send it back the right way (comment, request changes, or /colony:reimplement).
  4. Override — when automerge isn’t appropriate, block it.

Read the LLM review

Section titled “Read the LLM review”

Colony’s reviewer comments on the PR with three things:

  • Verdict — approve, request changes, or escalate to human review
  • Confidence flags — places the LLM is uncertain (often the most useful signal)
  • Specific findings — concrete issues, ranked by severity

Don’t treat the LLM review as competition. Treat it as a smart junior engineer’s first pass: it catches the obvious, it sometimes misses the deep, and its uncertainty flags are usually right about what to look at even when wrong about what’s wrong.

Judge architectural fit

Section titled “Judge architectural fit”

The deterministic checks already passed by the time you’re reading the PR. Your job is the things they can’t measure:

  • Grain. Does this code look like the rest of the codebase, or does it look like it was bolted on? An out-of-grain PR may work today but rots fast.
  • Intent. Does the implementation address the why in the issue, or just the what? A literal-minded fix can leave the original problem standing.
  • Hidden cost. Performance, complexity, surface area. The LLM reviewer flags some of this; your domain knowledge catches the rest.
  • Convention drift. If the PR introduces a new pattern, is the new pattern better, or just different? Drift compounds.

Escalate

Section titled “Escalate”

Three escalation paths, each with a different message:

WhatWhenHow
CommentA small fix or questionPlain GitHub comment. Colony reads it; the developer worker may iterate.
Request changesSpecific changes you want before mergeGitHub “Request changes” review. Blocks merge until addressed.
/colony:reimplementThe approach is fundamentally wrongSlash command on the PR. Colony discards the implementation and starts over with your guidance in the comment.

Use /colony:reimplement deliberately. It’s the right call when the PR’s structure is wrong; it’s the wrong call when the PR is 80% right and needs a tweak.

Override

Section titled “Override”

Colony auto-merges PRs that pass review. You can block automerge per-PR if a human needs to be the last to merge. Common reasons:

  • The PR touches a high-blast-radius surface and you want a deliberate human-in-the-loop merge
  • A freeze window is in effect (your team’s, not the colony’s)
  • You want to coordinate the merge with a runtime change

Marking the PR do-not-automerge (label or PR body, depending on repo config) keeps it at human-review-ready until you merge it manually.

Where you engage in the Workflow

Section titled “Where you engage in the Workflow”

Your tools

Section titled “Your tools”
  • GitHub PR UI — where you read the LLM review and form your judgment
  • /colony:reimplement — slash command on the PR; sends the PR back to development with your guidance
  • /colony:retry — slash command that re-runs the reviewer worker (useful if it errored)
  • Dashboard PR view — Cloud-only; cross-repo view of every Colony PR your team is responsible for

Anti-patterns

Section titled “Anti-patterns”
  • Approving without reading the LLM review. You miss the flagged uncertainty — the place a smart junior would have asked a question. Read the review even if you’d approve regardless.
  • Using /colony:reimplement for small fixes. It discards the work in progress. For a small fix, comment or request changes.
  • Treating Colony PRs differently from human PRs. If you wouldn’t approve the same diff from a colleague, don’t approve it from Colony. Same standards.
  • Never overriding automerge. Automerge is fine for most PRs; if you never block, you’re either lucky or not paying attention.

Going deeper

Section titled “Going deeper”