polar-code-review

---
name: polar-code-review
description: Review a Polar branch diff against conventions, Accepted ADRs, reuse, slop, and path-triggered API, ship-safety, and billing lenses. Use before opening a PR, when the user asks for a Polar code review, /polar-code-review, or $polar-code-review. Not a bug hunt or security review.
license: MIT
metadata:
  author: polar
  version: "1.0.0"
---

# Polar Code Review

Review the diff against the things only Polar knows: its conventions, its Accepted ADRs, its
shared helpers, its API contract, its deploy shape, its billing domain.

Not a bug hunt and not a security review — `/code-review` and `/security-review` do those
better, and they verify findings and can apply fixes. This adds what they cannot know.

This is only a router. Every lens is a skill you can also run on its own.

## 1. Diff

```bash
git fetch origin main
git diff origin/main --stat
git diff origin/main
```

That is the branch plus the working tree. If fetch fails, use `main` instead of `origin/main`.
Keep the full diff — every agent gets it, not just file names.

## 2. Route

Run the first four always. Add the rest only when the trigger matches.

| Skill | Runs when |
|---|---|
| `conventions-check` | always |
| `adr-check` | always |
| `reuse-check` | always |
| `slop-check` | always |
| `api-surface-review` | `**/schemas.py`, `**/endpoints.py`, `polar/openapi.py`, `docs/openapi.json`, `sdk/`, `clients/packages/client/` |
| `ship-safety` | `migrations/versions/`, `**/tasks.py`, `polar/models/`, `server/scripts/`; an endpoint is removed; or the diff spans `server/` and `clients/` with a dependency between them |
| `billing-review` | the billing paths listed in that skill's Scope section |

## 3. Launch

Launch one independent subagent per selected skill in a single turn. They must not wait
on each other. Use the host's general-purpose agent type (`general-purpose` in Claude
Code, `generalPurpose` in Cursor, `general` if that is all the host exposes).
Same prompt for every lens:

```
Read `.agents/skills/<skill name>/SKILL.md` and follow it exactly.

Review this diff. Only changed lines are in scope — never the rest of the repo.

[INSERT FULL DIFF]

Use the output format the skill defines. High-confidence findings only. If you are unsure
whether something is a defect, put it under Question instead of asserting it.
```

Each skill declares what it does **not** own, so the lenses do not overlap by construction.

`adr-check` predates this skill and has its own terser format: either `No violations`, or a
list of ADR id, `file:line`, what breaks, and the fix. Map its findings to 🔴.

## 4. Merge

- **Deduplicate.** One line, one finding. Precedence when two lenses hit the same line:
  `billing-review` → `api-surface-review` → `ship-safety` → `adr-check` →
  `conventions-check` → `reuse-check` → `slop-check`.
- **Surface conflicts.** If two lenses disagree, say so rather than picking silently.
- **Cut the padding.** A short report that is all true beats a long one that is half true.

## 5. Report

```markdown
## Polar Review

### 🔴 Blocking
- **[lens]** `file:line` — <what breaks>. Fix: <fix>

### 🟠 Should fix
- **[lens]** `file:line` — <claim>. Fix: <fix>

### 🟡 Questions
- **[lens]** `file:line` — <question>

### 🧹 Delete
- `file:line-line` — <why>

### Notes
<deploy notes from ship-safety, surface delta from api-surface-review. Omit if neither ran.>

### Coverage
Ran: <...>. Skipped: <...> (no matching paths).

### Verdict
✅ APPROVED  |  ❌ CHANGES REQUESTED — n blocking, n should-fix
```

Any 🔴 means CHANGES REQUESTED. 🟠 alone is a judgement call: say which way you lean and why.
The 🟡 section is expected to have content — Polar reviews are mostly questions.

More agent context in polarsource/polar

24 other files this repository gives its agents.